Гостевая книга

Работа с базой гостей ресторана: список, поиск, создание и редактирование профилей, карточка гостя с историей визитов. Через эти эндпоинты партнёрское приложение (CRM, POS, маркетинговый сервис) может синхронизировать клиентскую базу, обогащать профили предпочтениями гостей и получать историю их посещений.

Все эндпоинты — под Bearer-токеном (см. Аутентификация). Общие соглашения по запросам и формату ошибок — в разделах Соглашения и Ошибки.

Базовый путь: /api/loyalty/admin/restaurants/{restaurantId}/....

Исторически база гостей обслуживается под префиксом /api/loyalty/..., а сущность в API называется member. В этой документации это просто гость — без привязки к программе лояльности.

Профиль гостя (CustomerContract)

Большинство эндпоинтов чтения возвращают объект CustomerContract — полную карточку гостя. Ниже — ключевые поля. Поля только для чтения (агрегаты, счётчики визитов) рассчитываются системой и при создании/обновлении игнорируются.

Идентификация и контакты

Предпочтения и признаки

Важные даты

Статистика гостя (только чтение)

Вложенные объекты

GET /members — список гостей

Возвращает гостей ресторана с поддержкой OData-фильтрации, сортировки и постраничного вывода.

Параметры

Пример

curl -G https://api.hostmeapp.com/api/loyalty/admin/restaurants/123/members \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode '$top=50' \
  --data-urlencode '$orderby=lastVisitDate desc'

Точная схема успешного ответа (200) в спецификации не зафиксирована. По смыслу эндпоинт возвращает коллекцию гостей (CustomerContract); для постраничного варианта с общим количеством используйте GET /members/search.

POST /members — создать гостя

Создаёт нового гостя в базе ресторана. Тело — CustomerUpdateContract.

Поля тела

Пример

curl -X POST https://api.hostmeapp.com/api/loyalty/admin/restaurants/123/members \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Иван Петров",
    "phoneNumber": "+79991234567",
    "email": "ivan@example.com",
    "vip": true,
    "vegetarian": false,
    "allergy": ["орехи"],
    "tablePreferences": "Столик у окна",
    "guestTags": [{ "name": "Постоянный", "color": "#DD7352" }]
  }'

Ответ. При успехе — 201 Created с созданным гостем (CustomerContract). Документированные ошибки: тело — ProblemDetails (см. Ошибки).

GET /members/{memberId} — получить гостя

Возвращает гостя по идентификатору.

PUT /members/{memberId} — обновить гостя

Обновляет профиль гостя. Тело — тот же CustomerUpdateContract, что и при создании; присылайте изменяемые поля.

curl -X PUT https://api.hostmeapp.com/api/loyalty/admin/restaurants/123/members/456 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "aboutGuestNotes": "Любит столик у окна", "vip": true }'

DELETE /members/{memberId} — удалить гостя

Удаляет гостя из базы ресторана.

curl -X DELETE https://api.hostmeapp.com/api/loyalty/admin/restaurants/123/members/456 \
  -H "Authorization: Bearer $TOKEN"

GET /members/find — найти по телефону

Ищет гостя по номеру телефона — удобно перед созданием, чтобы не плодить дубли.

curl -G https://api.hostmeapp.com/api/loyalty/admin/restaurants/123/members/find \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "phoneNumber=+79991234567"

GET /members/email/{email} — найти по email

Ищет гостя по адресу электронной почты.

curl https://api.hostmeapp.com/api/loyalty/admin/restaurants/123/members/email/ivan@example.com \
  -H "Authorization: Bearer $TOKEN"

GET /members/search — постраничный поиск

Постраничный поиск гостей с OData-фильтром и токеном продолжения. Возвращает PagedResult с массивом полных профилей и общим количеством.

Параметры

Ответ (PagedResult<CustomerContract>)

curl -G https://api.hostmeapp.com/api/loyalty/admin/restaurants/123/members/search \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode '$filter=contains(fullName,'"'"'Иван'"'"')' \
  --data-urlencode 'take=25'

GET /members/filter — облегчённый список профилей

Возвращает упрощённые карточки гостей (CustomerProfileContract) — полезно для списков и автодополнения, где не нужна вся статистика.

Параметры

Ответ — массив CustomerProfileContract

POST /members/export — экспорт базы гостей

Запускает экспорт списка гостей (например, в файл/выгрузку). Тело — ExportInfoCustomersContract.

curl -X POST https://api.hostmeapp.com/api/loyalty/admin/restaurants/123/members/export \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "filter": "vip eq true" }'

Ответ. 201 Created — экспорт принят в обработку.

История визитов

Три эндпоинта возвращают визиты гостя в разных срезах. Все принимают необязательный restaurantIds — чтобы агрегировать историю по нескольким ресторанам сети.

GET /members/{memberId}/visits — прошлые визиты

GET /members/{memberId}/inprogress — текущие визиты

Визиты, которые идут прямо сейчас (гость за столом).

GET /members/{memberId}/upcomingvisits — предстоящие визиты

Будущие брони гостя.

curl -G https://api.hostmeapp.com/api/loyalty/admin/restaurants/123/members/456/visits \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "take=20" \
  --data-urlencode "orderBy=date desc"

Карточка гостя

GET /customer/{memberId} — карточка гостя

Возвращает карточку гостя по идентификатору.

GET /guest/{memberId}/details — детали гостя

Возвращает детальную информацию о госте.

curl https://api.hostmeapp.com/api/loyalty/admin/restaurants/123/customer/ABC_ID \
  -H "Authorization: Bearer $TOKEN"

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