REST API TapTime

Każde żądanie wymaga klucza API firmy (Integracje → Webhooki i API w panelu) przesyłanego jako Authorization: Bearer tt_live_…. Odpowiedzi i błędy są w formacie JSON.

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

Uwierzytelnianie

Każde żądanie zawiera klucz API firmy jako token typu Bearer. Klucz tworzy się w panelu — Integracje → Webhooki i API → Klucze REST API — gdzie jest wyświetlany jeden raz, a po stronie serwera przechowywany wyłącznie jako skrót SHA-256; utracony klucz się unieważnia i zastępuje nowym, nie da się go odzyskać. Firma może mieć do 10 aktywnych kluczy.

• Klucze tylko do odczytu mogą wywoływać każdy endpoint GET oraz subskrybować i anulować webhooki — subskrypcja nie wysyła niczego, czego klucz nie mógłby już odczytać.
• Klucze do odczytu i zapisu mogą dodatkowo wysyłać żądanie POST zmieniające status rezerwacji; klucz tylko do odczytu otrzymuje na tych ścieżkach 403 Forbidden.
• Klucz należy do jednej firmy — każda lista i każde wyszukiwanie są już do niej zawężone, nie ma parametru companyId.

Limity żądań

50 żądań na minutę na klucz, w oknie przesuwnym, wspólnie dla wszystkich endpointów. Po przekroczeniu zwracany jest kod 429 Too Many Requests; należy odczekać i ponowić żądanie zamiast odpytywać częściej — albo zasubskrybować webhook i przestać odpytywać.

Endpointy

Obiekt rezerwacji

Rezerwacja stolika i wizyta mają jeden wspólny kształt: kind, id, status, source, guestInitiated, startsAt/endsAt/timezone (strefa czasowa oddziału), currency, company, branch, guest, attribution, conversionId, createdAt/updatedAt — a do tego partySize i table dla rezerwacji stolika oraz service i specialist dla wizyty. To dokładnie to, co dostarcza webhook, więc odbiorca obsługujący jedno obsługuje oba.

{
  "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…" }
  }
}

Obiekt zamówienia

Zamówienie ma jeden kształt, niezależnie od miejsca, w którym się pojawia — REST API, webhooki zamówień, strumień zdarzeń: kind ("order"), id, number (numer wywoływany przez personel), status (open lub paid), source (customer lub staff), guestInitiated, fulfilment, table, label, deliveryAddress, note, currency, timezone, company, branch, customer (uczestnik programu lojalnościowego, jeśli personel go zidentyfikował), items (name, variant, quantity, unitPriceCents, subtotalCents), itemCount, subtotalCents, discountCents, deliveryFeeCents, tipCents, totalCents, valueCents (wartość zamówienia bez napiwku — liczba raportowana w konwersjach), paymentMethod, servedBy, conversionId, createdAt, paidAt i attribution. Kwoty są zawsze w jednostkach podrzędnych waluty (np. groszach).

{
  "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…" }
  }
}

Obiekt lojalnościowy

Każde zdarzenie lojalnościowe, karta i nagroda mają jeden wspólny kształt: kind ("loyalty"), id (karta), timezone, company, branch (miejsce zdarzenia, jeśli jest), program (id, name, stampsRequired, rewardTitle), customer (id, name, phone, locale), card (id, status, stampsCount, stampsRequired, stampsToReward, createdAt), stamp (dla pieczątki: source, issuedBy, createdAt) i reward (dla nagrody: code, title, status, expiresAt, redeemedAt, redeemedBy), a także conversionId — identyfikator, pod którym raportowane jest dołączenie do programu lojalnościowego.

{
  "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…"
}

Strumień zdarzeń

Każdy wiersz to { id, cursor, type, createdAt, previousStatus, data }. data zawiera obiekt pod kluczem wskazanym przez prefiks zdarzenia: data.booking, data.order lub data.loyalty. Należy zapisywać najwyższy przetworzony kursor i przekazywać go z powrotem jako after — nigdy nie pomija ani nie powtarza wiersza, więc można bezpiecznie wznowić pracę po awarii. Nieobsługiwane typy należy ignorować: mogą pojawiać się nowe.

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

Webhooki

Wystarczy utworzyć endpoint w sekcji Integracje → Webhooki i API — lub podłączyć Zapier, Make, n8n albo Pipedream w sekcji Integracje → Automatyzacja — a TapTime wyśle żądanie POST z podpisanym zdarzeniem JSON w chwili, gdy zmieni się rezerwacja, zamówienie lub karta lojalnościowa. Zdarzenia wybiera się dla każdego endpointu osobno. Firma może mieć łącznie do 50 webhooków, postbacków, czatów i połączeń z platformami automatyzacji.

• Każda odpowiedź 2xx oznacza doręczenie; odpowiedź inna niż 2xx lub przekroczenie czasu skutkuje ponowieniem z rosnącymi odstępami (1m, 5m, 15m, 1h, 3h, 6h, 12h), maksymalnie 8 prób — odpowiedź 410 kończy ponawianie.
• Przekierowania nie są obsługiwane.
• W środowisku produkcyjnym adres URL musi używać HTTPS i nie może wskazywać na adres prywatny ani pętli zwrotnej.
• Doręczenie odbywa się co najmniej raz: zawsze należy weryfikować podpis i usuwać duplikaty według 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));

Subskrypcje webhooków

Platformy automatyzacji włączają i wyłączają wyzwalacze przez API, zamiast prosić użytkownika o wklejenie adresu URL („REST hooks”): wysyłają żądanie POST z własnym adresem URL platformy i żądanymi zdarzeniami, zachowują zwrócony identyfikator i wysyłają DELETE po wyłączeniu wyzwalacza. Subskrypcja to zwykły podpisany webhook — widoczny w panelu i oznaczony kluczem, który go utworzył.

• Klucz widzi i usuwa wyłącznie utworzone przez siebie subskrypcje; unieważnienie klucza usuwa je wszystkie.
• Adresy w domenach hooks.zapier.com, make.com i pipedream.net są rozpoznawane i wyświetlane z nazwą platformy; każdy inny adres https to zwykły webhook.
• Klucz podpisu jest zwracany jeden raz, w odpowiedzi na żądanie POST; właściciel może go ponownie wyświetlić w panelu.

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"]}'

Postbacki

Żądanie GET lub POST na własny adres URL trackera z wypełnionymi makrami — dla platform, które obsługują postbacki w parametrach zapytania zamiast webhooków JSON. W przypadku zamówienia {value} to wartość zamówienia bez napiwku, a {order_id} — jego identyfikator.

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

Dostępne makra

• {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}

Błędy

Każdy błąd jest zwracany w formacie JSON: { "error": "<kod>", "message": "<opis czytelny dla człowieka>" }.