TapTime REST API

Katram pieprasījumam nepieciešama uzņēmuma API atslēga (panelī Integrācijas → Webhooks un API), kas tiek nosūtīta kā Authorization: Bearer tt_live_…. Atbildes un kļūdas ir JSON formātā.

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

Autentifikācija

Katrs pieprasījums satur uzņēmuma API atslēgu kā bearer marķieri. Izveidojiet to panelī — Integrācijas → Webhooks un API → REST API atslēgas —, kur tā tiek parādīta vienreiz un serverī tiek glabāta tikai kā SHA-256 jaucējvērtība; pazaudēta atslēga tiek atsaukta un aizstāta, nevis atjaunota. Uzņēmumam var būt līdz 10 aktīvām atslēgām.

• Tikai lasīšanas atslēgas var izsaukt katru GET galapunktu, kā arī abonēt un atteikties no webhooks — abonements nesūta neko, ko atslēga jau nevarētu nolasīt.
• Lasīšanas un rakstīšanas atslēgas var arī ar POST mainīt rezervācijas statusu; tikai lasīšanas atslēga šajos maršrutos saņem 403 Forbidden.
• Atslēga pieder vienam uzņēmumam — katrs saraksts un vaicājums jau ir ierobežots ar to, parametra companyId nav.

Pieprasījumu ierobežojumi

50 pieprasījumi minūtē uz vienu atslēgu, slīdošā logā, kopīgi visiem galapunktiem. Pārsniedzot tiek atgriezts 429 Too Many Requests; pagaidiet un mēģiniet vēlreiz, nevis vaicājiet biežāk — vai abonējiet webhook un pārtrauciet vaicāšanu.

Galapunkti

Rezervācijas objekts

Rezervācija un pieraksts tiek atgriezti vienā kopīgā struktūrā: kind, id, status, source, guestInitiated, startsAt/endsAt/timezone (filiāles laika josla), currency, company, branch, guest, attribution, conversionId, createdAt/updatedAt — kā arī partySize un table rezervācijai, service un specialist pierakstam. Tas ir tieši tas, ko nogādā webhook, tāpēc saņēmējs, kas apstrādā vienu, apstrādā abus.

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

Pasūtījuma objekts

Pasūtījums vienmēr ir vienā struktūrā, lai kur Jūs to sastaptu — REST API, pasūtījumu webhooks, notikumu plūsmā: kind ("order"), id, number (čeka numurs, ko izsauc darbinieki), status (open vai paid), source (customer vai staff), guestInitiated, fulfilment, table, label, deliveryAddress, note, currency, timezone, company, branch, customer (lojalitātes dalībnieks, ja darbinieki to identificējuši), items (name, variant, quantity, unitPriceCents, subtotalCents), itemCount, subtotalCents, discountCents, deliveryFeeCents, tipCents, totalCents, valueCents (pasūtījuma vērtība bez dzeramnaudas — skaitlis, ko ziņo konversijas), paymentMethod, servedBy, conversionId, createdAt, paidAt un attribution. Naudas summas vienmēr ir mazākajās vienībās.

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

Lojalitātes objekts

Katram lojalitātes notikumam, kartei un balvai ir viena struktūra: kind ("loyalty"), id (karte), timezone, company, branch (kur tas notika, ja tāda ir), program (id, name, stampsRequired, rewardTitle), customer (id, name, phone, locale), card (id, status, stampsCount, stampsRequired, stampsToReward, createdAt), stamp (zīmogam: source, issuedBy, createdAt) un reward (balvai: code, title, status, expiresAt, redeemedAt, redeemedBy), kā arī conversionId — id, ar kuru tiek ziņota lojalitātes programmas pievienošanās.

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

Notikumu plūsma

Katra rinda ir { id, cursor, type, createdAt, previousStatus, data }. data satur objektu zem atslēgas, ko nosaka notikuma prefikss: data.booking, data.order vai data.loyalty. Saglabājiet augstāko apstrādāto kursoru un nododiet to atpakaļ kā after — tas nekad neizlaiž un neatkārto rindu, tāpēc pēc avārijas var droši turpināt. Ignorējiet veidus, kurus neapstrādājat: var tikt pievienoti jauni.

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

Webhooks

Izveidojiet galapunktu sadaļā Integrācijas → Webhooks un API — vai pieslēdziet Zapier, Make, n8n vai Pipedream sadaļā Integrācijas → Automatizācija —, lai TapTime ar POST nosūtītu parakstītu JSON notikumu tajā brīdī, kad mainās rezervācija, pasūtījums vai lojalitātes karte. Notikumus izvēlaties katram galapunktam. Uzņēmumam var būt kopā līdz 50 webhooks, postbacks, tērzēšanas un automatizācijas savienojumu.

• Jebkura 2xx atbilde tiek uzskatīta par piegādātu; atbilde, kas nav 2xx, vai noildze tiek atkārtota ar pieaugošu intervālu (1m, 5m, 15m, 1h, 3h, 6h, 12h) līdz 8 mēģinājumiem — 410 aptur atkārtošanu.
• Pāradresācijām netiek sekots.
• Ražošanas vidē URL jābūt HTTPS, un tas nedrīkst norādīt uz privātu vai loopback adresi.
• Piegāde notiek vismaz vienreiz: vienmēr pārbaudiet parakstu un atfiltrējiet dublikātus pēc 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));

Webhook abonementi

Automatizācijas platformas ieslēdz un izslēdz trigerus caur API, nevis lūdz lietotājam ielīmēt URL (“REST hooks”): ar POST nosūtiet platformas URL ar vajadzīgajiem notikumiem, saglabājiet atgriezto id un ar DELETE dzēsiet to, kad trigeris tiek izslēgts. Abonements ir parasts parakstīts webhook — tas redzams panelī, atzīmēts ar atslēgu, kas to izveidoja.

• Atslēga redz un noņem tikai savus izveidotos abonementus; atslēgas atsaukšana noņem tos visus.
• Adreses domēnos hooks.zapier.com, make.com un pipedream.net tiek atpazītas un parādītas ar platformas nosaukumu; jebkura cita https adrese ir parasts webhook.
• Parakstīšanas noslēpums tiek atgriezts vienreiz, atbildē uz POST; īpašnieks to var atkal apskatīt panelī.

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

Postbacks

GET vai POST pieprasījums uz Jūsu izsekotāja URL ar aizpildītiem makro, platformām, kas izmanto vaicājuma virknes postbacks, nevis JSON webhooks. Pasūtījumam {value} ir pasūtījuma vērtība bez dzeramnaudas un {order_id} — tā id.

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

Pieejamie vietturi

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

Kļūdas

Katra kļūda ir JSON: { "error": "<code>", "message": "<human-readable>" }.