TapTime REST API

Elk verzoek heeft een API-sleutel van het bedrijf nodig (Integraties → Webhooks & API in het dashboard), verzonden als Authorization: Bearer tt_live_…. Antwoorden en fouten zijn JSON.

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

Authenticatie

Elk verzoek bevat een API-sleutel van het bedrijf als bearer-token. Maak er een aan in het dashboard — Integraties → Webhooks & API → REST API-sleutels — waar hij één keer wordt getoond en op de server alleen als SHA-256-hash wordt bewaard; een verloren sleutel wordt ingetrokken en vervangen, niet hersteld. Een bedrijf kan maximaal 10 actieve sleutels hebben.

• Alleen-lezen-sleutels kunnen elk GET-endpoint aanroepen en webhooks aan- en afmelden — een abonnement verstuurt niets wat de sleutel niet al kon lezen.
• Lees-schrijfsleutels kunnen daarnaast een statuswijziging van een reservering POSTen; een alleen-lezen-sleutel krijgt op die routes 403 Forbidden.
• Een sleutel hoort bij één bedrijf — elke lijst en elke opvraging is daar al toe beperkt, er is geen companyId-parameter.

Rate limits

50 verzoeken per minuut per sleutel, in een glijdend venster, gedeeld door alle endpoints. Ga je eroverheen, dan krijg je 429 Too Many Requests; wacht en probeer opnieuw in plaats van sneller te pollen — of abonneer een webhook en stop met pollen.

Endpoints

Het reserveringsobject

Een reservering en een afspraak komen in één gedeelde vorm: kind, id, status, source, guestInitiated, startsAt/endsAt/timezone (de eigen tijdzone van de vestiging), currency, company, branch, guest, attribution, conversionId, createdAt/updatedAt — plus partySize en table voor een reservering, service en specialist voor een afspraak. Het is precies wat een webhook levert, dus een ontvanger die het ene verwerkt, verwerkt ook het andere.

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

Het bestelobject

Een bestelling heeft overal dezelfde vorm — in de REST API, de bestelwebhooks en de eventfeed: kind ("order"), id, number (het bonnummer dat het personeel omroept), status (open of paid), source (customer of staff), guestInitiated, fulfilment, table, label, deliveryAddress, note, currency, timezone, company, branch, customer (het loyaliteitslid, als het personeel er een herkende), items (name, variant, quantity, unitPriceCents, subtotalCents), itemCount, subtotalCents, discountCents, deliveryFeeCents, tipCents, totalCents, valueCents (wat de bestelling waard is zonder fooi — het getal dat conversies rapporteren), paymentMethod, servedBy, conversionId, createdAt, paidAt en attribution. Bedragen staan altijd in de kleinste munteenheid.

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

Het loyaliteitsobject

Elk loyaliteitsevent, elke kaart en elke beloning heeft één vorm: kind ("loyalty"), id (de kaart), timezone, company, branch (waar het gebeurde, als dat bekend is), program (id, name, stampsRequired, rewardTitle), customer (id, name, phone, locale), card (id, status, stampsCount, stampsRequired, stampsToReward, createdAt), stamp (bij een stempel: source, issuedBy, createdAt) en reward (bij een beloning: code, title, status, expiresAt, redeemedAt, redeemedBy), plus conversionId, het id waaronder een loyaliteitsaanmelding wordt gerapporteerd.

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

Eventfeed

Elke rij is { id, cursor, type, createdAt, previousStatus, data }. data bevat het onderwerp onder de sleutel die het voorvoegsel van het event noemt: data.booking, data.order of data.loyalty. Bewaar de hoogste cursor die je hebt verwerkt en geef die terug als after — er wordt nooit een rij overgeslagen of herhaald, dus hervatten na een crash is veilig. Negeer types die je niet verwerkt: er kunnen nieuwe bijkomen.

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

Webhooks

Maak een endpoint aan onder Integraties → Webhooks & API — of koppel Zapier, Make, n8n of Pipedream onder Integraties → Automatisering — en TapTime POST een ondertekend JSON-event zodra een reservering, een bestelling of een spaarkaart verandert. Per endpoint kies je de events. Een bedrijf kan in totaal maximaal 50 webhooks, postbacks, chats en automatiseringskoppelingen hebben.

• Elk 2xx-antwoord geldt als geleverd; een niet-2xx-antwoord of een time-out wordt opnieuw geprobeerd met oplopende wachttijd (1m, 5m, 15m, 1u, 3u, 6u, 12u) tot 8 pogingen — een 410 stopt de nieuwe pogingen.
• Redirects worden niet gevolgd.
• De URL moet in productie HTTPS zijn en mag niet naar een privé- of loopbackadres wijzen.
• Levering is at-least-once: verifieer altijd de handtekening en ontdubbel op 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));

Webhookabonnementen

Automatiseringsplatforms zetten triggers aan en uit via de API, in plaats van de gebruiker een URL te laten plakken (‘REST hooks’): POST de eigen URL van het platform met de gewenste events, bewaar het teruggegeven id en DELETE het wanneer de trigger wordt uitgezet. Een abonnement is een gewone ondertekende webhook — het staat in het dashboard, gemarkeerd met de sleutel die het aanmaakte.

• Een sleutel ziet en verwijdert alleen de abonnementen die hij zelf aanmaakte; de sleutel intrekken verwijdert ze allemaal.
• Adressen op hooks.zapier.com, make.com en pipedream.net worden herkend en met de naam van het platform getoond; elk ander https-adres is een gewone webhook.
• Het ondertekeningsgeheim wordt één keer teruggegeven, in het antwoord op de POST; de eigenaar kan het in het dashboard opnieuw tonen.

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

Een GET of POST naar de eigen URL van je tracker met ingevulde macro's, voor platforms die postbacks via querystrings gebruiken in plaats van JSON-webhooks. Voor een bestelling is {value} de waarde van de bestelling zonder fooi en {order_id} haar id.

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

Beschikbare placeholders

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

Fouten

Elke fout is JSON: { "error": "<code>", "message": "<leesbare tekst>" }.