TapTime REST API

Для каждого запроса требуется API-ключ компании (раздел «Интеграции» → «Вебхуки и API» в панели управления), который необходимо отправить в поле «Authorization: Bearer tt_live_….». Ответы и ошибки передаются в формате JSON.

curl "https://api.tapti.me/v1/company/reservations?status=confirmed&updatedSince=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer tt_live_…"

Аутентификация

Каждый запрос содержит API-ключ компании в качестве токена «bearer». Создайте его в панели управления — «Интеграции» → «Вебхуки и API» → «Ключи REST API» — где он отображается однократно и хранится на стороне сервера исключительно в виде хеша SHA-256; утерянный ключ аннулируется и заменяется, но не восстанавливается. Компания может иметь до 10 активных ключей.

• Ключи только для чтения могут вызывать любую конечную точку GET, а также подписывать и отписывать веб-хуки — подписка не передаёт ничего, что ключ не мог бы прочитать и так.
• Ключи для чтения и записи также могут менять статус бронирования запросом POST; ключ только для чтения получает на этих маршрутах ответ 403 Forbidden.
• Ключ принадлежит одной компании — все списки и запросы уже ограничены ею, параметра companyId нет.

Ограничения по скорости

50 запросов в минуту на ключ в скользящем окне — общий лимит для всех конечных точек. При превышении возвращается 429 Too Many Requests; сделайте паузу и повторите запрос, а не опрашивайте чаще — или подпишите веб-хук и перестаньте опрашивать вовсе.

Конечные точки

Объект бронирования

Бронирование и запись на прием представлены в виде одного общего шаблона: тип, идентификатор, статус, источник, guestInitiated, startsAt/endsAt/часовой пояс (пояс филиала), валюта, компания, филиал, гость, атрибуция, conversionId, createdAt/updatedAt — плюс partySize и таблица для бронирования, услуга и специалист для записи на приём. Это именно то, что передаёт веб-хук, поэтому получатель, обрабатывающий одно из них, обрабатывает и другое.

{
  "data": {
    "kind": "reservation",
    "id": 4821,
    "status": "confirmed",
    "source": "online",
    "guestInitiated": true,
    "startsAt": "2026-09-12T20:00:00+03:00",
    "endsAt": "2026-09-12T21:30:00+03:00",
    "timezone": "Asia/Baku",
    "currency": "AZN",
    "company": { "id": 12, "name": "Cafe Aroma", "slug": "cafe-aroma", "country": "AZ" },
    "branch": { "id": 3, "name": "Nizami st." },
    "partySize": 4,
    "table": { "id": 9, "label": "T3" },
    "guest": { "name": "Maria K.", "phone": "…", "email": "…" },
    "locale": "en",
    "note": null,
    "conversionId": "tt3f9c…",
    "createdAt": "2026-09-10T08:12:04+00:00",
    "updatedAt": "2026-09-12T20:00:03+00:00",
    "attribution": { "channel": "widget", "utmSource": "instagram", "gclid": null, "fbclid": "IwAR2…" }
  }
}

Объект заказа

Заказ выглядит одинаково везде — в REST API, в веб-хуках заказов и в ленте событий: kind ("order"), id, number (номер, который называет персонал), status (open или paid), source (customer или staff), guestInitiated, fulfilment, table, label, deliveryAddress, note, currency, timezone, company, branch, customer (участник программы лояльности, если персонал его указал), items (name, variant, quantity, unitPriceCents, subtotalCents), itemCount, subtotalCents, discountCents, deliveryFeeCents, tipCents, totalCents, valueCents (стоимость заказа без чаевых — именно эту сумму передают конверсии), paymentMethod, servedBy, conversionId, createdAt, paidAt и attribution. Суммы всегда указаны в минимальных единицах валюты.

{
  "data": {
    "kind": "order",
    "id": 9170,
    "number": 42,
    "status": "paid",
    "source": "customer",
    "guestInitiated": true,
    "fulfilment": "takeaway",
    "table": null,
    "label": "Ana",
    "currency": "EUR",
    "branch": { "id": 3, "name": "Vitosha Blvd" },
    "customer": { "id": 311, "name": "Ana", "phone": "…" },
    "items": [
      { "menuItemId": 88, "name": "Flat white", "variant": "Large",
        "quantity": 2, "unitPriceCents": 450, "subtotalCents": 900 }
    ],
    "itemCount": 2,
    "subtotalCents": 900,
    "discountCents": 0,
    "deliveryFeeCents": 0,
    "tipCents": 100,
    "totalCents": 1000,
    "valueCents": 900,
    "paymentMethod": "online",
    "conversionId": "tt81ad…",
    "createdAt": "2026-09-12T12:04:10+03:00",
    "paidAt": "2026-09-12T12:05:02+03:00",
    "attribution": { "channel": "web", "utmSource": "google", "gclid": "Cj0K…" }
  }
}

Объект лояльности

Все события, карты и награды лояльности имеют один формат: kind ("loyalty"), id (карта), timezone, company, branch (где это произошло, если применимо), program (id, name, stampsRequired, rewardTitle), customer (id, name, phone, locale), card (id, status, stampsCount, stampsRequired, stampsToReward, createdAt), stamp (для штампа: source, issuedBy, createdAt) и reward (для награды: code, title, status, expiresAt, redeemedAt, redeemedBy), а также conversionId — идентификатор, под которым передаётся регистрация в программе лояльности.

{
  "kind": "loyalty",
  "id": 5120,
  "program": { "id": 4, "name": "Coffee card", "stampsRequired": 8, "rewardTitle": "Free coffee" },
  "customer": { "id": 311, "name": "Ana", "phone": "…", "locale": "bg" },
  "card": { "id": 5120, "status": "active", "stampsCount": 5,
            "stampsRequired": 8, "stampsToReward": 3 },
  "branch": { "id": 3, "name": "Vitosha Blvd" },
  "stamp": { "source": "qr_scan", "issuedBy": "Ivan", "createdAt": "…" },
  "reward": null,
  "conversionId": "tt5c02…"
}

Лента событий

Каждая строка имеет вид { id, cursor, type, createdAt, previousStatus, data }. В data лежит объект под ключом, который задаёт префикс события: data.booking, data.order или data.loyalty. Сохраняйте наибольший обработанный курсор и передавайте его обратно в after — строки никогда не пропускаются и не повторяются, поэтому после сбоя можно спокойно продолжить. Игнорируйте типы, которые вы не обрабатываете: могут появиться новые.

curl "https://api.tapti.me/v1/company/events?after=998&limit=100" \
  -H "Authorization: Bearer tt_live_…"

Веб-хуки

Создайте конечную точку в разделе «Интеграции» → «Вебхуки и API» — или подключите Zapier, Make, n8n или Pipedream в разделе «Интеграции» → «Автоматизация», — и TapTime будет отправлять подписанное событие в формате JSON методом POST в момент, когда меняется бронирование, заказ или карта лояльности. События выбираются отдельно для каждой конечной точки. У компании может быть до 50 веб-хуков, постбэков, чатов и подключений автоматизации в сумме.

• Любой ответ с кодом 2xx считается доставленным; в случае ответа, отличного от 2xx, или истечения времени ожидания повторная попытка осуществляется с интервалом отсрочки (1 мин, 5 мин, 15 мин, 1 ч, 3 ч, 6 ч, 12 ч) до 8 попыток — при получении кода 410 повторные попытки прекращаются.
• Перенаправления не обрабатываются.
• В производственной среде URL-адрес должен использовать протокол HTTPS и не должен указывать на частный или петлевой адрес.
• Доставка осуществляется как минимум один раз: всегда проверяйте подпись и удаляйте дубликаты по TapTime-Event-Id.

{
  "id": "evt_9f3c2a7e1b",
  "type": "booking.confirmed",
  "createdAt": "2026-09-12T19:02:11+03:00",
  "test": false,
  "data": { "booking": { "kind": "reservation", "id": 4821, "status": "confirmed", "…": "…" } }
}

const [t, v1] = req.headers["taptime-signature"]
  .split(",").map(part => part.split("=")[1]);
const expected = crypto
  .createHmac("sha256", process.env.TAPTIME_WEBHOOK_SECRET)
  .update(`${t}.${rawBody}`)
  .digest("hex");
const valid = crypto.timingSafeEqual(
  Buffer.from(expected), Buffer.from(v1));

Подписки на веб-хуки

Платформы автоматизации включают и выключают триггеры через API, а не просят пользователя вставить URL («REST hooks»): отправьте POST с собственным URL платформы и нужными событиями, сохраните возвращённый id и удалите подписку запросом DELETE, когда триггер выключат. Подписка — обычный подписанный веб-хук: она видна в панели с отметкой ключа, который её создал.

• Ключ видит и удаляет только созданные им подписки; при отзыве ключа удаляются все они.
• Адреса на hooks.zapier.com, make.com и pipedream.net распознаются и показываются с названием платформы; любой другой адрес https — обычный веб-хук.
• Секрет подписи возвращается один раз — в ответе на POST; владелец может снова посмотреть его в панели.

curl -X POST "https://api.tapti.me/v1/company/webhooks" \
  -H "Authorization: Bearer tt_live_…" -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.zapier.com/hooks/catch/123/abc/", "events": ["order.placed"]}'

Отправка данных

GET- или POST-запрос на собственный URL вашего трекера с заполненными макросами — для платформ, которые принимают постбэки в строке запроса, а не JSON-вебхуки. Для заказа {value} — сумма заказа без чаевых, а {order_id} — его идентификатор.

https://tracker.example/postback
  ?cid={click_id}&event={event}&status={status}
  &payout={value}&cur={currency}

Доступные заполнители

• {event}
• {event_id}
• {status}
• {booking_id}
• {booking_type}
• {order_id}
• {customer_id}
• {conversion_id}
• {value}
• {currency}
• {party_size}
• {branch_id}
• {timestamp}
• {utm_source}
• {utm_medium}
• {utm_campaign}
• {utm_term}
• {utm_content}
• {gclid}
• {fbclid}
• {msclkid}
• {ttclid}
• {click_id}

Ошибки

Каждая ошибка имеет формат JSON: { "error": "<code>", "message": "<human-readable>" }.