TapTime REST API

Kiekvienai užklausai reikia įmonės API rakto (valdymo skyde Integracijos → Webhooks ir API), siunčiamo kaip Authorization: Bearer tt_live_…. Atsakymai ir klaidos pateikiami JSON formatu.

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

Autentifikacija

Kiekvienoje užklausoje siunčiamas įmonės API raktas kaip bearer žetonas. Jį sukursite valdymo skyde — Integracijos → Webhooks ir API → REST API raktai — kur jis parodomas vieną kartą, o serveryje saugomas tik kaip SHA-256 maiša; prarastas raktas atšaukiamas ir pakeičiamas, o ne atkuriamas. Įmonė gali turėti iki 10 aktyvių raktų.

• Tik skaitymo raktai gali kviesti visus GET galinius taškus ir gali prenumeruoti bei atšaukti webhooks — prenumerata nesiunčia nieko, ko raktas ir taip negalėtų perskaityti.
• Skaitymo ir rašymo raktai taip pat gali siųsti POST rezervacijos būsenos pakeitimui; tik skaitymo raktas šiuose maršrutuose gauna 403 Forbidden.
• Raktas priklauso vienai įmonei — kiekvienas sąrašas ir paieška jau apriboti ja, companyId parametro nėra.

Užklausų limitai

50 užklausų per minutę vienam raktui, slenkančiu langu, bendrai visiems galiniams taškams. Viršijus limitą grąžinama 429 Too Many Requests; palaukite ir bandykite iš naujo, užuot užklausę dažniau — arba užsiprenumeruokite webhook ir nustokite užklausinėti.

Galiniai taškai

Rezervacijos objektas

Rezervacija ir vizitas pateikiami viena bendra struktūra: kind, id, status, source, guestInitiated, startsAt/endsAt/timezone (paties filialo laiko juosta), currency, company, branch, guest, attribution, conversionId, createdAt/updatedAt — bei partySize ir table rezervacijai, service ir specialist vizitui. Tai lygiai tai, ką pristato webhook, todėl gavėjas, apdorojantis vieną, apdoros ir kitą.

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

Užsakymo objektas

Užsakymas visur pateikiamas viena struktūra — REST API, užsakymų webhooks, įvykių sraute: kind ("order"), id, number (numeris, kurį iškviečia personalas), status (open arba paid), source (customer arba staff), guestInitiated, fulfilment, table, label, deliveryAddress, note, currency, timezone, company, branch, customer (lojalumo narys, kai personalas jį identifikavo), items (name, variant, quantity, unitPriceCents, subtotalCents), itemCount, subtotalCents, discountCents, deliveryFeeCents, tipCents, totalCents, valueCents (užsakymo vertė be arbatpinigių — skaičius, kurį praneša konversijos), paymentMethod, servedBy, conversionId, createdAt, paidAt ir attribution. Sumos visada nurodomos smulkiaisiais vienetais.

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

Lojalumo objektas

Kiekvienas lojalumo įvykis, kortelė ir prizas turi vieną struktūrą: kind ("loyalty"), id (kortelė), timezone, company, branch (kur tai įvyko, jei yra), program (id, name, stampsRequired, rewardTitle), customer (id, name, phone, locale), card (id, status, stampsCount, stampsRequired, stampsToReward, createdAt), stamp (štampui: source, issuedBy, createdAt) ir reward (prizui: code, title, status, expiresAt, redeemedAt, redeemedBy), taip pat conversionId — id, kuriuo pranešama apie lojalumo registraciją.

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

Įvykių srautas

Kiekviena eilutė yra { id, cursor, type, createdAt, previousStatus, data }. data saugo objektą po raktu, kurį nurodo įvykio priešdėlis: data.booking, data.order arba data.loyalty. Išsaugokite didžiausią apdorotą cursor ir perduokite jį atgal kaip after — jis niekada nepraleidžia ir nepakartoja eilutės, todėl saugu tęsti po gedimo. Ignoruokite neapdorojamus tipus: gali būti pridėta naujų.

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

Webhooks

Sukurkite galinį tašką skiltyje Integracijos → Webhooks ir API — arba prijunkite Zapier, Make, n8n ar Pipedream skiltyje Integracijos → Automatizavimas — ir TapTime išsiųs pasirašytą JSON įvykį tą pačią akimirką, kai pasikeičia rezervacija, užsakymas ar lojalumo kortelė. Įvykius pasirenkate kiekvienam galiniam taškui. Įmonė iš viso gali turėti iki 50 webhooks, postbacks, pokalbių ir automatizavimo jungčių.

• Bet koks 2xx atsakymas laikomas pristatytu; ne 2xx atsakymas arba laiko viršijimas kartojamas su atidėjimu (1m, 5m, 15m, 1h, 3h, 6h, 12h) iki 8 bandymų — 410 sustabdo kartojimą.
• Peradresavimai nesekami.
• Produkcinėje aplinkoje URL turi būti HTTPS ir negali rodyti į privatų ar loopback adresą.
• Pristatymas vyksta bent kartą: visada tikrinkite parašą ir šalinkite dublikatus pagal 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 prenumeratos

Automatizavimo platformos įjungia ir išjungia trigerius per API, užuot prašiusios naudotojo įklijuoti URL („REST hooks“): siųskite POST su platformos URL ir norimais įvykiais, išsaugokite grąžintą id ir siųskite DELETE, kai trigeris išjungiamas. Prenumerata yra įprastas pasirašytas webhook — ji rodoma valdymo skyde, pažymėta ją sukūrusiu raktu.

• Raktas mato ir šalina tik savo sukurtas prenumeratas; atšaukus raktą, pašalinamos visos jos.
• Adresai hooks.zapier.com, make.com ir pipedream.net atpažįstami ir rodomi su platformos pavadinimu; bet kuris kitas https adresas yra paprastas webhook.
• Pasirašymo slaptas raktas grąžinamas vieną kartą, atsakyme į POST; savininkas gali jį vėl parodyti valdymo skyde.

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 arba POST užklausa į Jūsų sekimo sistemos URL su užpildytais makrokomandų kintamaisiais — platformoms, naudojančioms užklausos eilutės postbacks, o ne JSON webhooks. Užsakymui {value} yra užsakymo vertė be arbatpinigių, o {order_id} — jo id.

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

Galimi kintamieji

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

Klaidos

Kiekviena klaida pateikiama JSON formatu: { "error": "<code>", "message": "<human-readable>" }.