API REST TapTime

Fiecare solicitare necesită o cheie API a companiei (Integrări → Webhooks și API în panoul de control), trimisă sub forma „Authorization: Bearer tt_live_….”. Răspunsurile și erorile sunt în format JSON.

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

Autentificare

Fiecare solicitare conține o cheie API a companiei ca token de tip „bearer”. Creați una din panoul de control — Integrări → Webhooks și API → Chei API REST — unde aceasta este afișată o singură dată și stocată pe server doar sub forma unui hash SHA-256; o cheie pierdută este revocată și înlocuită, nu recuperată. O companie poate deține până la 10 chei active.

• Cheile doar pentru citire pot apela orice endpoint GET și pot abona sau dezabona webhook-uri — o abonare nu trimite nimic din ce cheia nu ar putea deja citi.
• Cheile de citire-scriere pot, în plus, să schimbe prin POST starea unei rezervări; o cheie doar pentru citire primește 403 Forbidden pe aceste rute.
• O cheie aparține unei singure companii — fiecare listă și căutare este deja limitată la ea; nu există parametrul companyId.

Limite de rată

50 de cereri pe minut pentru fiecare cheie, într-o fereastră glisantă, comune tuturor endpointurilor. La depășire răspunsul este 429 Too Many Requests; așteptați și reîncercați în loc să interogați mai des — sau abonați un webhook și renunțați la interogări.

Puncte terminale

Obiectul de rezervare

O rezervare și o programare au aceeași structură: tip, ID, stare, sursă, guestInitiated, startsAt/endsAt/fus orar (fusul orar propriu al sucursalei), monedă, companie, sucursală, oaspete, atribuire, conversionId, createdAt/updatedAt — plus partySize și tabelul pentru o rezervare, serviciul și specialistul pentru o programare. Este exact ceea ce furnizează un webhook, așa că un receptor care gestionează una le gestionează pe amândouă.

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

Obiectul de comandă

O comandă are aceeași formă oriunde o întâlniți — în REST API, în webhook-urile de comenzi și în fluxul de evenimente: kind ("order"), id, number (numărul pe care îl strigă personalul), status (open sau paid), source (customer sau staff), guestInitiated, fulfilment, table, label, deliveryAddress, note, currency, timezone, company, branch, customer (membrul programului de fidelizare, când personalul l-a identificat), items (name, variant, quantity, unitPriceCents, subtotalCents), itemCount, subtotalCents, discountCents, deliveryFeeCents, tipCents, totalCents, valueCents (valoarea comenzii fără bacșiș — cifra raportată de conversii), paymentMethod, servedBy, conversionId, createdAt, paidAt și attribution. Sumele sunt întotdeauna în subunități monetare.

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

Obiectul de fidelizare

Fiecare eveniment, card și recompensă de fidelizare are aceeași formă: kind ("loyalty"), id (cardul), timezone, company, branch (locul unde s-a întâmplat, dacă există), program (id, name, stampsRequired, rewardTitle), customer (id, name, phone, locale), card (id, status, stampsCount, stampsRequired, stampsToReward, createdAt), stamp (pentru o ștampilă: source, issuedBy, createdAt) și reward (pentru o recompensă: code, title, status, expiresAt, redeemedAt, redeemedBy), plus conversionId, id-ul sub care este raportată o înscriere la fidelizare.

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

Flux de evenimente

Fiecare rând are forma { id, cursor, type, createdAt, previousStatus, data }. data conține subiectul sub cheia numită de prefixul evenimentului: data.booking, data.order sau data.loyalty. Păstrați cel mai mare cursor procesat și transmiteți-l înapoi ca after — nu sare și nu repetă niciodată un rând, deci puteți relua în siguranță după o cădere. Ignorați tipurile pe care nu le tratați: pot apărea altele noi.

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

Webhooks

Creați un endpoint în Integrări → Webhook-uri și API — sau conectați Zapier, Make, n8n ori Pipedream în Integrări → Automatizare — ca TapTime să trimită prin POST un eveniment JSON semnat în momentul în care se schimbă o rezervare, o comandă sau un card de fidelitate. Alegeți evenimentele pentru fiecare endpoint. O companie poate avea în total până la 50 de webhook-uri, postback-uri, chaturi și conexiuni de automatizare.

• Orice răspuns din seria 2xx este considerat ca fiind livrat; în cazul unui răspuns care nu aparține seriei 2xx sau al unei depășiri a timpului de așteptare, se efectuează o nouă încercare cu interval de așteptare (1 min, 5 min, 15 min, 1 oră, 3 ore, 6 ore, 12 ore), până la un număr maxim de 8 încercări — un cod de stare 410 oprește repetarea încercărilor.
• Redirecționările nu sunt urmate.
• Adresa URL trebuie să fie de tip HTTPS în mediul de producție și nu poate indica o adresă privată sau de loopback.
• Livrarea se efectuează cel puțin o dată: verificați întotdeauna semnătura și eliminați duplicatele la 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));

Abonări la webhook-uri

Platformele de automatizare activează și dezactivează declanșatoarele prin API, în loc să-i ceară utilizatorului să lipească un URL („REST hooks”): trimiteți prin POST URL-ul propriu al platformei cu evenimentele dorite, păstrați id-ul returnat și ștergeți-l cu DELETE când declanșatorul este oprit. O abonare este un webhook semnat obișnuit — apare în panou, marcată cu cheia care a creat-o.

• O cheie vede și elimină doar abonările pe care le-a creat; revocarea cheii le elimină pe toate.
• Adresele de pe hooks.zapier.com, make.com și pipedream.net sunt recunoscute și afișate cu numele platformei; orice altă adresă https este un webhook obișnuit.
• Secretul de semnare este returnat o singură dată, în răspunsul la POST; proprietarul îl poate afișa din nou în panou.

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

Postback-uri

O cerere GET sau POST către URL-ul propriu al trackerului dvs., cu macrourile completate, pentru platformele care folosesc postback-uri prin query string în loc de webhook-uri JSON. Pentru o comandă, {value} este valoarea comenzii fără bacșiș, iar {order_id} este id-ul ei.

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

Simboluri de substituție disponibile

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

Erori

Fiecare eroare este de tip JSON: { "error": "<code>", "message": "<human-readable>" }.