TapTime REST API

Iga päring vajab ettevõtte API-võtit (paneelis Integratsioonid → Veebihaagid ja API), mis saadetakse kujul Authorization: Bearer tt_live_…. Vastused ja vead on JSON-vormingus.

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

Autentimine

Iga päring kannab ettevõtte API-võtit bearer-tokenina. Loo see paneelis – Integratsioonid → Veebihaagid ja API → REST API võtmed –, kus seda näidatakse üks kord ja serveris hoitakse ainult selle SHA-256 räsi; kadunud võti tühistatakse ja asendatakse, seda ei taastata. Ettevõttel võib olla kuni 10 aktiivset võtit.

• Lugemisõigusega võtmed saavad kutsuda iga GET-otspunkti ning tellida ja tühistada veebihaake – tellimus ei saada midagi, mida võti poleks niigi lugeda saanud.
• Lugemis- ja kirjutamisõigusega võtmed saavad lisaks POST-päringuga muuta broneeringu olekut; lugemisõigusega võti saab neil marsruutidel vastuseks 403 Forbidden.
• Võti kuulub ühele ettevõttele – iga loend ja päring on juba selle ettevõttega piiratud, companyId parameetrit ei ole.

Päringupiirangud

50 päringut minutis võtme kohta, libiseva aknaga, ühine kõigile otspunktidele. Piirangu ületamisel tagastatakse 429 Too Many Requests; oota ja proovi uuesti, selle asemel et kiiremini pärida – või telli veebihaak ja lõpeta pärimine.

Otspunktid

Broneeringu objekt

Lauabroneering ja ajabroneering väljastatakse ühisel kujul: kind, id, status, source, guestInitiated, startsAt/endsAt/timezone (filiaali enda ajavöönd), currency, company, branch, guest, attribution, conversionId, createdAt/updatedAt – lisaks partySize ja table lauabroneeringul ning service ja specialist ajabroneeringul. See on täpselt see, mida veebihaak edastab, nii et vastuvõtja, mis käsitleb üht, käsitleb mõlemat.

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

Tellimuse objekt

Tellimus väljastatakse ühel kujul, kus iganes sellega kokku puutud – REST API, tellimuste veebihaagid, sündmuste voog: kind ("order"), id, number (tšeki number, mille töötajad välja hüüavad), status (open või paid), source (customer või staff), guestInitiated, fulfilment, table, label, deliveryAddress, note, currency, timezone, company, branch, customer (püsikliendiprogrammi liige, kui töötaja ta tuvastas), items (name, variant, quantity, unitPriceCents, subtotalCents), itemCount, subtotalCents, discountCents, deliveryFeeCents, tipCents, totalCents, valueCents (tellimuse väärtus ilma jootrahata – number, mida konversioonid raporteerivad), paymentMethod, servedBy, conversionId, createdAt, paidAt ja attribution. Summad on alati väikseimates rahaühikutes.

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

Püsikliendiprogrammi objekt

Iga püsikliendisündmus, kaart ja auhind on ühel kujul: kind ("loyalty"), id (kaart), timezone, company, branch (kus see juhtus, kui on), program (id, name, stampsRequired, rewardTitle), customer (id, name, phone, locale), card (id, status, stampsCount, stampsRequired, stampsToReward, createdAt), stamp (templi puhul: source, issuedBy, createdAt) ja reward (auhinna puhul: code, title, status, expiresAt, redeemedAt, redeemedBy), lisaks conversionId – id, mille all püsikliendiprogrammiga liitumist raporteeritakse.

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

Sündmuste voog

Iga rida on { id, cursor, type, createdAt, previousStatus, data }. data sisaldab subjekti võtme all, mille nimetab sündmuse eesliide: data.booking, data.order või data.loyalty. Salvesta suurim töödeldud cursor ja anna see tagasi parameetris after – see ei jäta kunagi rida vahele ega korda seda, nii et pärast krahhi on ohutu jätkata. Ignoreeri tüüpe, mida sa ei käsitle: uusi võidakse lisada.

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

Veebihaagid

Loo otspunkt jaotises Integratsioonid → Veebihaagid ja API – või ühenda Zapier, Make, n8n või Pipedream jaotises Integratsioonid → Automatiseerimine –, et TapTime saadaks POST-päringuga allkirjastatud JSON-sündmuse kohe, kui broneering, tellimus või püsikliendikaart muutub. Sündmused valid iga otspunkti jaoks eraldi. Ettevõttel võib kokku olla kuni 50 veebihaaki, postbacki, vestlust ja automatiseerimisühendust.

• Iga 2xx vastust loetakse edastatuks; mitte-2xx vastust või aegumist proovitakse uuesti kasvavate vahedega (1m, 5m, 15m, 1h, 3h, 6h, 12h) kuni 8 korda – vastus 410 lõpetab kordamise.
• Ümbersuunamisi ei järgita.
• Tootmiskeskkonnas peab URL olema HTTPS ega tohi osutada privaatsele ega loopback-aadressile.
• Edastus toimub vähemalt üks kord: kontrolli alati allkirja ja eemalda duplikaadid TapTime-Event-Id järgi.

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

Veebihaakide tellimused

Automatiseerimisplatvormid lülitavad päästikuid sisse ja välja API kaudu, selle asemel et paluda kasutajal URL kleepida („REST hooks“): saada POST-päringuga platvormi enda URL koos soovitud sündmustega, hoia tagastatud id alles ja kustuta see DELETE-päringuga, kui päästik välja lülitatakse. Tellimus on tavaline allkirjastatud veebihaak – see kuvatakse paneelis ja on märgitud võtmega, mis selle lõi.

• Võti näeb ja eemaldab ainult enda tehtud tellimusi; võtme tühistamine eemaldab need kõik.
• Aadressid domeenidel hooks.zapier.com, make.com ja pipedream.net tuvastatakse ja kuvatakse platvormi nimega; mis tahes muu https-aadress on tavaline veebihaak.
• Allkirjastamise saladus tagastatakse üks kord, POST-päringu vastuses; omanik saab selle paneelis uuesti nähtavaks teha.

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

Postbackid

GET- või POST-päring sinu jälgija enda URL-ile täidetud makrodega – platvormidele, mis kasutavad päringustringiga postbacke, mitte JSON-veebihaake. Tellimuse puhul on {value} tellimuse väärtus ilma jootrahata ja {order_id} selle id.

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

Saadaolevad kohatäitjad

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

Vead

Iga viga on JSON: { "error": "<code>", "message": "<human-readable>" }.