Вебхуки, серверные постбэки и REST API

Три способа подключить TapTime к другим системам, собранные в одном разделе. Управлять ими может только владелец компании. Об уведомлениях в чатах и о Zapier, Make, n8n или Pipedream читайте в отдельных инструкциях — они используют те же события.

Панель Интеграции Вебхуки и API

Что использовать	Когда
Вебхук	Ваша система или CRM должна узнавать о каждом изменении бронирования, заказа или карты лояльности со всеми подробностями.
Постбэк	Рекламная сеть, партнёрская программа или трекер дали вам URL постбэка, который нужно вызывать при каждой конверсии.
REST API	Ваша система хочет получать бронирования, когда ей удобно, или подтверждать и отменять их.

События, которые можно отправлять

Событие	Когда
booking.requested	Гость запросил бронирование, которое ждёт вашего подтверждения
booking.confirmed	Бронирование подтверждено
booking.cancelled	Гость или заведение отменили бронирование
booking.no_show	Гость не пришёл
booking.completed	Визит завершён
order.placed	Заказ гостя поступил к вам (с вашей страницы или по QR-коду стола)
order.paid	Любой заказ оплачен, в том числе на кассе
loyalty.member_joined	Клиент получил первый штамп в программе
loyalty.stamp_added	Добавлен штамп
loyalty.reward_issued	Карта заполнена, награда начислена
loyalty.reward_redeemed	Награда выдана гостю

Вебхуки

1
Добавить вебхук
Вставьте https-адрес вашего эндпоинта и выберите события — бронирования, заказы, лояльность или все сразу.
2
Отправить тест
Тестовое событие уходит сразу, и вы видите, что ответил ваш эндпоинт.
3
Проверьте подпись
У каждого запроса есть заголовок TapTime-Signature: t=<time>,v1=<HMAC-SHA256 от «t.body» с вашим секретом подписи>. Сверьте её, прежде чем доверять запросу.

Тело запроса — JSON: ID, тип и время события и всё бронирование, заказ или карта лояльности в data.booking, data.order или data.loyalty — с гостем, временем, столом, услугой или позициями, статусом и источником (UTM-метки и ID кликов).

Отвечайте любым статусом 2xx. Всё остальное повторяется 8 раз в течение примерно суток.
У каждого события есть ID: если получили его дважды, игнорируйте второе.
Ответьте 410 Gone — и TapTime перестанет повторять это событие.
Редиректы не выполняются, а адреса в частных сетях отклоняются.

Серверные постбэки

Вставьте URL постбэка, который дал вам трекер, и нажимайте на макросы, чтобы подставить данные бронирования, например https://tracker.example/postback?cid={click_id}&payout={value}&status={status}. Среди доступных макросов — {click_id}, {event}, {booking_id}, {value}, {currency}, {party_size}, {utm_source}, {utm_campaign}, {gclid} и {fbclid}. ID клика из трекера попадает в бронирование, когда ваша ссылка на бронирование содержит click_id, clickid или subid.

REST API

1
Создать API-ключ
Дайте ему название и выберите «Только чтение» или «Чтение и запись», чтобы разрешить подтверждать, отменять и отмечать неявки.
2
Сразу скопируйте его
Ключ показывается один раз. Храните его на своём сервере — никогда на веб-странице или в приложении.
3
Вызовите API
Передавайте его как Authorization: Bearer <key> на https://api.tapti.me/v1/company.

Запрос	Возвращает
GET /v1/company	Компанию, которой принадлежит ключ
GET /v1/company/reservations, /appointments	Бронирования с фильтрами status, branchId, from, to или updatedSince, по 100 на страницу
GET /v1/company/reservations/{id}	Одно бронирование
POST /v1/company/reservations/{id}/status	Изменяет статус (ключи на запись)
GET /v1/company/orders, /orders/{id}	Заказы с позициями и суммами; фильтры status, source, fulfilment, from, to или paidSince
GET /v1/company/loyalty/programs, /cards, /rewards	Программы лояльности, карты участников и полученные ими награды
GET /v1/company/events?after={cursor}	Все события бронирований, заказов и лояльности по порядку — опрашивайте ленту, чтобы оставаться в синхроне; добавьте type=order,loyalty, чтобы получать только часть
POST /v1/company/webhooks, DELETE /v1/company/webhooks/{id}	Подписать URL на события и отписать его — это используют приложения Zapier, Make, n8n и Pipedream

Если что-то не работает

«Журнал отправок» каждого эндпоинта показывает его последние 25 отправок с кодом статуса и ответом вашей системы. Неудачные отправки повторяются сами; «Отправить снова» повторяет одну из них сразу.

Частые вопросы

Можно ли отправлять вебхук в Zapier или Make?

Да — используйте Интеграции → Автоматизация: там проверяется, что адрес принадлежит платформе, и показаны её собственные шаги. Создайте «Catch hook» (Zapier), «Custom webhook» (Make), узел Webhook (n8n) или HTTP-триггер (Pipedream), вставьте его адрес и нажмите «Отправить тест», чтобы сервис узнал поля.

Я потерял секрет подписи.

Владелец может снова открыть его в настройках эндпоинта или сменить. При смене сразу выпускается новый секрет, а старый перестаёт работать.

Статья была полезной?

Это не ответило на ваш вопрос?

Напишите нам и укажите страницу, на которой вы были. Каждое сообщение читает человек, а ответ приходит на том языке, на котором вы написали.

Напишите нам