TapTime REST API

Minden kéréshez céges API-kulcs szükséges (a kezelőfelületen: Integrációk → Webhookok és API), Authorization: Bearer tt_live_… formában elküldve. A válaszok és a hibák JSON formátumúak.

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

Hitelesítés

Minden kérés bearer tokenként egy céges API-kulcsot tartalmaz. Kulcsot a kezelőfelületen hozhat létre — Integrációk → Webhookok és API → REST API-kulcsok —, ahol egyszer jelenik meg, és a szerveren csak SHA-256 hashként tároljuk; az elveszett kulcsot visszavonjuk és lecseréljük, nem állítjuk helyre. Egy cégnek legfeljebb 10 aktív kulcsa lehet.

• A csak olvasási jogú kulcsok minden GET végpontot meghívhatnak, és webhookokra fel- és leiratkozhatnak — egy feliratkozás semmi olyat nem küld, amit a kulcs ne tudna amúgy is olvasni.
• Az olvasási-írási jogú kulcsok POST kéréssel foglalási állapotot is módosíthatnak; egy csak olvasási jogú kulcs ezeken az útvonalakon 403 Forbidden választ kap.
• Egy kulcs egyetlen céghez tartozik — minden lista és lekérdezés eleve erre a cégre szűkül, nincs companyId paraméter.

Kéréskorlátok

Kulcsonként percenként 50 kérés, csúszó időablakkal, minden végpontra közösen. Túllépés esetén 429 Too Many Requests a válasz; várjon, és próbálja újra ahelyett, hogy gyakrabban kérdezne le — vagy iratkozzon fel egy webhookra, és hagyja abba a lekérdezést.

Végpontok

A foglalás objektum

Az asztalfoglalás és az időpontfoglalás egyetlen közös formában érkezik: kind, id, status, source, guestInitiated, startsAt/endsAt/timezone (a telephely saját időzónája), currency, company, branch, guest, attribution, conversionId, createdAt/updatedAt — valamint asztalfoglalásnál partySize és table, időpontfoglalásnál service és specialist. Pontosan ezt kézbesíti egy webhook is, így egy fogadó, amely az egyiket kezeli, a másikat is kezeli.

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

A rendelés objektum

A rendelés mindenhol ugyanabban a formában érkezik — a REST API-ban, a rendelési webhookokban és az eseményfolyamban: kind ("order"), id, number (a sorszám, amelyet a személyzet kiszól), status (open vagy paid), source (customer vagy staff), guestInitiated, fulfilment, table, label, deliveryAddress, note, currency, timezone, company, branch, customer (a hűségprogram tagja, ha a személyzet azonosította), items (name, variant, quantity, unitPriceCents, subtotalCents), itemCount, subtotalCents, discountCents, deliveryFeeCents, tipCents, totalCents, valueCents (a rendelés értéke borravaló nélkül — ezt az összeget jelentik a konverziók), paymentMethod, servedBy, conversionId, createdAt, paidAt és attribution. Az összegek mindig a pénznem legkisebb egységében szerepelnek.

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

A hűségprogram objektum

Minden hűségprogram-esemény, kártya és jutalom ugyanazt a formát használja: kind ("loyalty"), id (a kártya), timezone, company, branch (ahol történt, ha van ilyen), program (id, name, stampsRequired, rewardTitle), customer (id, name, phone, locale), card (id, status, stampsCount, stampsRequired, stampsToReward, createdAt), stamp (pecsétnél: source, issuedBy, createdAt) és reward (jutalomnál: code, title, status, expiresAt, redeemedAt, redeemedBy), valamint conversionId, az azonosító, amelyen egy hűségprogram-csatlakozást jelentünk.

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

Eseményfolyam

Minden sor { id, cursor, type, createdAt, previousStatus, data } formájú. A data az esemény előtagja által megnevezett kulcs alatt tartalmazza a tárgyat: data.booking, data.order vagy data.loyalty. Tárolja el a legmagasabb feldolgozott kurzort, és adja vissza after paraméterként — sosem hagy ki és sosem ismétel sort, így összeomlás után is biztonságosan folytatható. Hagyja figyelmen kívül azokat a típusokat, amelyeket nem kezel: újak is megjelenhetnek.

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

Webhookok

Hozzon létre egy végpontot az Integrációk → Webhookok és API menüpontban — vagy csatlakoztassa a Zapiert, a Make-et, az n8n-t vagy a Pipedreamet az Integrációk → Automatizálás menüpontban —, és a TapTime abban a pillanatban aláírt JSON-eseményt küld POST kéréssel, amikor egy foglalás, rendelés vagy hűségkártya megváltozik. Az eseményeket végpontonként választja ki. Egy cégnek összesen legfeljebb 50 webhookja, postbackje, chatje és automatizálási kapcsolata lehet.

• Bármely 2xx válasz kézbesítettnek számít; a nem 2xx válasz vagy az időtúllépés esetén fokozatosan növekvő várakozással újrapróbáljuk (1 perc, 5 perc, 15 perc, 1 óra, 3 óra, 6 óra, 12 óra), legfeljebb 8 kísérletig — a 410 leállítja az újrapróbálást.
• Az átirányításokat nem követjük.
• Éles környezetben az URL-nek HTTPS-nek kell lennie, és nem mutathat privát vagy loopback címre.
• A kézbesítés legalább egyszeri: mindig ellenőrizze az aláírást, és szűrje a duplikátumokat a TapTime-Event-Id alapján.

{
  "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));

Webhook-feliratkozások

Az automatizálási platformok az API-n keresztül kapcsolják be és ki a triggereket, ahelyett, hogy a felhasználót URL beillesztésére kérnék („REST hookok”): küldje el POST kéréssel a platform saját URL-jét a kívánt eseményekkel, őrizze meg a visszakapott azonosítót, és törölje DELETE kéréssel, amikor a triggert kikapcsolják. A feliratkozás egy szokásos aláírt webhook — megjelenik a kezelőfelületen, a létrehozó kulccsal megjelölve.

• Egy kulcs csak az általa létrehozott feliratkozásokat látja és távolíthatja el; a kulcs visszavonása mindegyiket eltávolítja.
• A hooks.zapier.com, a make.com és a pipedream.net címeit felismerjük, és a platform nevével jelenítjük meg; minden más https-cím egyszerű webhook.
• Az aláíró titkos kulcsot egyszer adjuk vissza, a POST kérésre adott válaszban; a tulajdonos a kezelőfelületen újra megjelenítheti.

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

Postbackek

GET vagy POST kérés a követőrendszere saját URL-jére, kitöltött makrókkal, azoknak a platformoknak, amelyek JSON-webhookok helyett lekérdezési karakterláncos postbacket használnak. Rendelésnél a {value} a rendelés értéke borravaló nélkül, az {order_id} pedig az azonosítója.

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

Elérhető helyőrzők

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

Hibák

Minden hiba JSON formátumú: { "error": "<code>", "message": "<human-readable>" }.