TapTime REST API

Svaki zahtev zahteva API ključ kompanije (Integracije → Vebhukovi i API u panelu) poslat kao Authorization: Bearer tt_live_….. Odgovori i greške su u JSON formatu.

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

Autentifikacija

Svaki zahtev nosi kompanijski API ključ kao token nosioca. Napravite ga na panelu — Integracije → Vebhukovi i API → REST API ključevi — gde se prikazuje samo jednom i čuva se samo na strani servera kao SHA-256 haš; izgubljeni ključ se poništava i zamenjuje, a ne vraća. Kompanija može imati najviše 10 aktivnih ključeva.

• Ključevi samo za čitanje mogu da pozivaju svaku GET krajnju tačku, kao i da pretplate i odjave vebhukove — pretplata ne šalje ništa što ključ ionako ne bi mogao da pročita.
• Ključevi za čitanje i pisanje mogu i da POST zahtevom promene status rezervacije; ključ samo za čitanje na tim rutama dobija 403 Forbidden.
• Ključ pripada jednoj kompaniji — svaka lista i pretraga već su ograničene na nju, parametar companyId ne postoji.

Ograničenja broja zahteva

50 zahteva u minuti po ključu, u kliznom prozoru, zajednički za sve krajnje tačke. Prekoračenje vraća 429 Too Many Requests; sačekajte i pokušajte ponovo umesto da češće šaljete upite — ili pretplatite vebhuk i prestanite da proveravate.

Krajnje tačke

Objekat rezervacije

Rezervacija i sastanak imaju isti zajednički oblik: kind, id, status, source, guestInitiated, startsAt/endsAt/timezone (zona filijale), currency, company, branch, guest, attribution, conversionId, createdAt/updatedAt — plus partySize i tabela za rezervaciju, usluga i specijalista za sastanak. To je upravo ono što vebhuk isporučuje, pa prijemnik koji obrađuje jedno obrađuje i oba.

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

Objekat porudžbine

Porudžbina ima isti oblik gde god da je sretnete — u REST API-ju, vebhukovima porudžbina i fidu događaja: kind ("order"), id, number (broj koji osoblje proziva), status (open ili paid), source (customer ili staff), guestInitiated, fulfilment, table, label, deliveryAddress, note, currency, timezone, company, branch, customer (član programa lojalnosti, kada ga je osoblje identifikovalo), items (name, variant, quantity, unitPriceCents, subtotalCents), itemCount, subtotalCents, discountCents, deliveryFeeCents, tipCents, totalCents, valueCents (vrednost porudžbine bez napojnice — broj koji prijavljuju konverzije), paymentMethod, servedBy, conversionId, createdAt, paidAt i attribution. Iznosi su uvek u najmanjim jedinicama valute.

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

Objekat lojalnosti

Svaki događaj, kartica i nagrada lojalnosti imaju isti oblik: kind ("loyalty"), id (kartica), timezone, company, branch (gde se desilo, ako postoji), program (id, name, stampsRequired, rewardTitle), customer (id, name, phone, locale), card (id, status, stampsCount, stampsRequired, stampsToReward, createdAt), stamp (za pečat: source, issuedBy, createdAt) i reward (za nagradu: code, title, status, expiresAt, redeemedAt, redeemedBy), plus conversionId, ID pod kojim se prijavljuje registracija u program lojalnosti.

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

Fid događaja

Svaki red je { id, cursor, type, createdAt, previousStatus, data }. data sadrži predmet događaja pod ključem koji određuje prefiks događaja: data.booking, data.order ili data.loyalty. Sačuvajte najveći kursor koji ste obradili i vratite ga kao after — nikada ne preskače niti ponavlja red, pa je bezbedno nastaviti posle pada. Zanemarite tipove koje ne obrađujete: mogu biti dodati novi.

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

Vebhukovi

Napravite krajnju tačku u odeljku Integracije → Vebhukovi i API — ili povežite Zapier, Make, n8n ili Pipedream u odeljku Integracije → Automatizacija — i TapTime će poslati POST sa potpisanim JSON događajem čim se promeni rezervacija, porudžbina ili kartica lojalnosti. Događaje birate za svaku krajnju tačku posebno. Kompanija može imati ukupno do 50 vebhukova, postbekova, četova i veza sa platformama za automatizaciju.

• Svaki 2xx odgovor se smatra isporučenim; ne-2xx odgovor ili istek vremena ponovo se pokušava sa produžavanjem intervala (1 min, 5 min, 15 min, 1 sat, 3 sata, 6 sati, 12 sati) do 8 pokušaja — kod 410 se prekida ponovno slanje.
• Preusmeravanja se ne prate.
• URL u produkciji mora biti HTTPS i ne sme upućivati na privatnu ili loopback adresu.
• Dostava se vrši barem jednom: uvek proverite potpis i uklonite duplikate na 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));

Pretplate na vebhukove

Platforme za automatizaciju uključuju i isključuju okidače preko API-ja, umesto da traže od korisnika da nalepi URL („REST hooks“): pošaljite POST sa URL-om platforme i događajima koje želi, sačuvajte vraćeni id i pošaljite DELETE kada se okidač isključi. Pretplata je običan potpisani vebhuk — prikazuje se u panelu, označena ključem koji ju je napravio.

• Ključ vidi i uklanja samo pretplate koje je sam napravio; opozivanje ključa uklanja ih sve.
• Adrese na hooks.zapier.com, make.com i pipedream.net se prepoznaju i prikazuju sa nazivom platforme; svaka druga https adresa je običan vebhuk.
• Tajni ključ za potpis vraća se jednom, u odgovoru na POST; vlasnik ga u panelu može ponovo prikazati.

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

Postbekovi

GET ili POST na URL vašeg trekera sa popunjenim makroima, za platforme koje koriste postbekove sa parametrima u URL-u umesto JSON vebhukova. Za porudžbinu, {value} je vrednost porudžbine bez napojnice, a {order_id} njen id.

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

Dostupni zamennici teksta

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

Greške

Svaka greška je JSON: { "error": "<code>", "message": "<human-readable>" }.