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 адрес на вашия тракер с попълнени макроси — за платформи, които приемат постбекове чрез параметри в 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>" }.