Регистрация приложения

Как внешнее приложение (партнёр, POS, CRM) регистрируется и получает доступ к Hostme API — appId, ключи и авторизация.

Эта страница описывает, как внешнее приложение (партнёр, POS, CRM) получает доступ к Hostme API: как выпустить партнёрский токен, узнать список своих ресторанов и partnerId, как устроена регистрация вендорского приложения и что такое appId.

Общие правила аутентификации — в разделе Аутентификация. Здесь — специфика именно партнёрского/вендорского доступа.

Часть схем запросов и ответов в этом разделе спецификации не зафиксирована (тело пустое или ответ не описан). Такие места отмечены явно — точный формат согласуется с командой Hostme на этапе онбординга.

Партнёрский токен

POST /api/core/admin/account/partners/token

Выпускает токен для партнёрского доступа. Тело запроса — PartnerTokenRequest.

Внимание. В спецификации тело PartnerTokenRequest пустое — конкретные поля (идентификатор партнёра, секрет и т.п.) в выгрузке не описаны. Формат запроса и набор учётных данных согласуются при онбординге с командой Hostme.

curl -X POST https://api.hostmeapp.com/api/core/admin/account/partners/token \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ }'

Полученный токен используется как Authorization: Bearer $TOKEN в остальных запросах. Поведение эндпоинтов может зависеть от типа токена (Hostme / Partner / Vendor) — например, при создании брони бронь оформляется от имени партнёра или внешнего приложения.

Кто я и мои рестораны

GET /api/core/admin/account/me

Возвращает UserInfoContract — данные текущего аккаунта, его partnerId и список ресторанов, к которым есть доступ. Это первый запрос после получения токена: из него вы берёте restaurantId для всех остальных вызовов и partnerId для партнёрских сценариев.

Ключевые поля ответа (`UserInfoContract`)

Поле	Тип	Описание
`id`	string	Идентификатор пользователя
`userName`	string	Логин
`email`	string	Email
`fullName`	string	Имя
`language`	string	Язык
`partnerId`	string	Идентификатор партнёра (если аккаунт партнёрский)
`roles`	array	Роли по ресторанам (`RoleInfoContract`: `restaurantId`, `restaurantName`, `name`, `type`)
`restaurants`	array	Доступные рестораны (`RestaurantSummaryContract`, см. ниже)

Ресторан в списке (`RestaurantSummaryContract`)

Поле	Тип	Описание
`id`	integer	`restaurantId` для API-вызовов
`name`	string	Название
`address`, `city`, `country`, `countryShort`	string	Адрес
`timeZone`	string	Часовой пояс
`isVerified`	boolean	Верифицирован
`isSuspended`	boolean	Приостановлен
`isOnline`	boolean	Онлайн
`role`	string	Ваша роль в этом ресторане

curl https://api.hostmeapp.com/api/core/admin/account/me \
  -H "Authorization: Bearer $TOKEN"

Регистрация вендорского приложения (`VendorSignup`)

Поток VendorSignup нужен, когда внешний сервис (POS/CRM) подключается к Hostme через OAuth-подобный сценарий: пользователь авторизуется на стороне вендора, Hostme получает callback и выпускает токен.

Ответы этих эндпоинтов в спецификации не описаны (RESPONSE 200 — OK без схемы). Используйте их по согласованию с Hostme; точные форматы уточняются при онбординге.

Эндпоинт	Назначение
`GET /api/vendor/signup/vendors`	Список доступных вендоров
`GET /api/vendor/signup/vendors/{vendorId}`	Информация о вендоре
`GET /api/vendor/signup/auth/callback/{vendorId}`	OAuth-callback (параметры: `code`, `state`, `account`, `merchant_id`, `employee_id`, `referer`)
`GET /api/vendor/signup/auth/token`	Выпуск токена (параметры: `vendorId`, `username`, `password`, `restaurantId`)
`GET /api/vendor/signup/token/hostme`	Токен Hostme по `connectionId`
`GET /api/vendor/signup/accounts`	Аккаунты вендора по `connectionId`
`GET /api/vendor/signup/locations`	Локации (`connectionId`, `accountId`)
`POST /api/vendor/signup/submit`	Создание ресторана из вендорского аккаунта (тело `CreateRestaurantContract`)

Заявка на подключение вендора

POST /api/vendor/signup/submit

Создаёт заведение по данным из вендорского аккаунта. Тело — CreateRestaurantContract (адрес, название, контакты, услуги, часы работы, connectionId, companyId, siteId и др.). Это объёмный объект; ключевые поля — name, phone, email, addressObj, openingHours, services, connectionId.

Полная схема CreateRestaurantContract — в Swagger UI.

Вендорское приложение (`VendorApp`) и `vendorId`

После регистрации приложение работает в пространстве /api/pos/apps/{vendorId}/…. Здесь vendorId — идентификатор вашего приложения. Через эти эндпоинты идут события и интеграции (телефония, печать, WhatsApp, статусы устройств).

Большинство эндпоинтов VendorApp — это входящие вебхуки конкретных провайдеров (телефония, AmoCRM и т.п.) и служебные операции. Ответы в спецификации не описаны. Подключение — по согласованию с Hostme.

Эндпоинт	Назначение
`GET /api/pos/apps/{vendorId}/auth2`	Авторизация приложения (параметр `token`)
`GET /api/pos/apps/{vendorId}/mappings/{entity}`	Маппинг сущностей
`POST /api/pos/apps/{vendorId}/events`	Приём событий (параметр `appId`)
`GET /api/pos/apps/{vendorId}/dashboard`	Дашборд приложения
`POST /api/pos/apps/{vendorId}/whatsapp/{restaurantId}/connect`	Подключение WhatsApp

Понятие `appId`

appId — идентификатор партнёрского/вендорского приложения. Он используется как фильтр и метка источника в ряде эндпоинтов. В частности, по нему строится путь к партнёрским броням:

/api/rsv/partner/{appId}/reservations

Подробнее о работе с бронями от имени приложения — в разделе Партнёрские брони. При листинге броней appId (как VendorAppId) может проставляться автоматически для запросов от внешних приложений — см. Создание и управление.

Возможные ошибки — ProblemDetails, коды 400/401/403/404. Общие правила см. в Соглашениях и разделе Ошибки.