REST API TapTime

Každý požadavek potřebuje API klíč firmy (Integrace → Webhooky a API v administraci) odeslaný jako Authorization: Bearer tt_live_…. Odpovědi i chyby jsou ve formátu JSON.

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

Ověření

Každý požadavek nese API klíč firmy jako bearer token. Vytvoříte ho v administraci – Integrace → Webhooky a API → Klíče REST API –, kde se zobrazí jen jednou a na serveru se uloží pouze jako hash SHA-256; ztracený klíč se zneplatní a nahradí, neobnovuje se. Firma může mít až 10 aktivních klíčů.

• Klíče jen pro čtení mohou volat všechny endpointy GET a mohou přihlašovat i odhlašovat webhooky – odběr neodešle nic, co by klíč nemohl přečíst i tak.
• Klíče pro čtení i zápis mohou navíc přes POST měnit stav rezervace; klíč jen pro čtení dostane na těchto cestách 403 Forbidden.
• Klíč patří jedné firmě – každý výpis i dotaz je na ni už omezen, parametr companyId neexistuje.

Limity požadavků

50 požadavků za minutu na klíč v klouzavém okně, společně pro všechny endpointy. Při překročení se vrací 429 Too Many Requests; počkejte a zkuste to znovu, místo abyste se dotazovali častěji – nebo si přihlaste webhook a dotazování ukončete.

Endpointy

Objekt rezervace

Rezervace stolu i termín mají jeden společný tvar: kind, id, status, source, guestInitiated, startsAt/endsAt/timezone (vlastní pásmo provozovny), currency, company, branch, guest, attribution, conversionId, createdAt/updatedAt – plus partySize a table u rezervace stolu, service a specialist u termínu. Je to přesně to, co doručuje webhook, takže příjemce, který zvládne jedno, zvládne obojí.

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

Objekt objednávky

Objednávka má jeden tvar, ať ji potkáte kdekoli – v REST API, ve webhoocích objednávek i v proudu událostí: kind ("order"), id, number (číslo lístku, které personál vyvolává), status (open nebo paid), source (customer nebo staff), guestInitiated, fulfilment, table, label, deliveryAddress, note, currency, timezone, company, branch, customer (člen věrnostního programu, pokud ho personál identifikoval), items (name, variant, quantity, unitPriceCents, subtotalCents), itemCount, subtotalCents, discountCents, deliveryFeeCents, tipCents, totalCents, valueCents (hodnota objednávky bez spropitného – číslo, které hlásí konverze), paymentMethod, servedBy, conversionId, createdAt, paidAt a attribution. Částky jsou vždy v nejmenších jednotkách měny.

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

Objekt věrnosti

Každá věrnostní událost, karta i odměna sdílí jeden tvar: kind ("loyalty"), id (karta), timezone, company, branch (kde k ní došlo, pokud je známo), program (id, name, stampsRequired, rewardTitle), customer (id, name, phone, locale), card (id, status, stampsCount, stampsRequired, stampsToReward, createdAt), stamp (u razítka: source, issuedBy, createdAt) a reward (u odměny: code, title, status, expiresAt, redeemedAt, redeemedBy), plus conversionId, id, pod kterým se hlásí registrace do věrnostního programu.

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

Proud událostí

Každý řádek je { id, cursor, type, createdAt, previousStatus, data }. data obsahuje předmět pod klíčem, který určuje prefix události: data.booking, data.order nebo data.loyalty. Uložte si nejvyšší zpracovaný cursor a předejte ho zpět jako after – nikdy nepřeskočí ani nezopakuje řádek, takže je bezpečné po pádu pokračovat. Typy, které nezpracováváte, ignorujte: mohou přibývat nové.

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

Webhooky

Vytvořte endpoint v sekci Integrace → Webhooky a API – nebo připojte Zapier, Make, n8n či Pipedream v sekci Integrace → Automatizace – a TapTime odešle podepsanou JSON událost metodou POST ve chvíli, kdy se změní rezervace, objednávka nebo věrnostní karta. Události volíte pro každý endpoint zvlášť. Firma může mít dohromady až 50 webhooků, postbacků, chatů a automatizačních propojení.

• Jakákoli odpověď 2xx se považuje za doručení; odpověď mimo 2xx nebo vypršení časového limitu se opakuje s odstupem (1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h) až do 8 pokusů – odpověď 410 opakování zastaví.
• Přesměrování se nenásledují.
• URL musí být v produkci HTTPS a nesmí mířit na privátní ani loopback adresu.
• Doručení je alespoň jednou: vždy ověřte podpis a odstraňujte duplicity podle 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));

Odběry webhooků

Automatizační platformy zapínají a vypínají spouštěče přes API, místo aby uživatele žádaly o vložení URL („REST hooks“): pošlete POST s vlastní URL platformy a požadovanými událostmi, uložte si vrácené id a při vypnutí spouštěče ho smažte přes DELETE. Odběr je běžný podepsaný webhook – zobrazuje se v administraci a je označen klíčem, který ho vytvořil.

• Klíč vidí a odstraňuje jen odběry, které sám vytvořil; zneplatnění klíče odstraní všechny.
• Adresy na hooks.zapier.com, make.com a pipedream.net se rozpoznají a zobrazí s názvem platformy; jakákoli jiná adresa https je běžný webhook.
• Podpisový klíč se vrací jen jednou, v odpovědi na POST; majitel si ho může v administraci znovu zobrazit.

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

Postbacky

Požadavek GET nebo POST na vlastní URL vašeho trackeru s vyplněnými makry, pro platformy, které místo JSON webhooků používají postbacky v query stringu. U objednávky je {value} hodnota objednávky bez spropitného a {order_id} její id.

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

Dostupné zástupné symboly

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

Chyby

Každá chyba je JSON: { "error": "<code>", "message": "<human-readable>" }.