API REST TapTime

Chaque requête nécessite une clé API de l’entreprise (Intégrations → Webhooks et API dans le panneau de gestion), envoyée sous la forme Authorization: Bearer tt_live_…. Les réponses et les erreurs sont au format JSON.

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

Authentification

Chaque requête transporte une clé API de l’entreprise sous forme de jeton Bearer. Créez-en une depuis le panneau de gestion — Intégrations → Webhooks et API → Clés API REST — où elle n’est affichée qu’une seule fois et n’est conservée côté serveur que sous forme de hachage SHA-256 ; une clé perdue est révoquée et remplacée, jamais récupérée. Une entreprise peut détenir jusqu’à 10 clés actives.

• Les clés en lecture seule peuvent appeler tous les endpoints GET, ainsi qu’abonner et désabonner des webhooks — un abonnement ne transmet rien que la clé ne pourrait déjà lire.
• Les clés en lecture-écriture peuvent en outre envoyer un changement de statut de réservation en POST ; une clé en lecture seule reçoit 403 Forbidden sur ces routes.
• Une clé appartient à une seule entreprise — chaque liste et chaque consultation y sont déjà restreintes, il n’existe pas de paramètre companyId.

Limites de débit

50 requêtes par minute et par clé, sur une fenêtre glissante, partagées entre tous les endpoints. Un dépassement renvoie 429 Too Many Requests ; patientez et réessayez plutôt que d’interroger plus vite — ou abonnez un webhook et cessez d’interroger.

Endpoints

L’objet réservation

Une réservation de table et un rendez-vous sont renvoyés dans un format commun : kind, id, status, source, guestInitiated, startsAt/endsAt/timezone (le fuseau horaire propre à l’établissement), currency, company, branch, guest, attribution, conversionId, createdAt/updatedAt — plus partySize et table pour une réservation, service et specialist pour un rendez-vous. C’est exactement ce que livre un webhook : un récepteur qui gère l’un gère l’autre.

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

L’objet commande

Une commande se présente sous un format unique où que vous la rencontriez — l’API REST, les webhooks de commande, le flux d’événements : kind ("order"), id, number (le numéro de ticket annoncé par le personnel), status (open ou paid), source (customer ou staff), guestInitiated, fulfilment, table, label, deliveryAddress, note, currency, timezone, company, branch, customer (le membre fidélité, lorsque le personnel l’a identifié), items (name, variant, quantity, unitPriceCents, subtotalCents), itemCount, subtotalCents, discountCents, deliveryFeeCents, tipCents, totalCents, valueCents (la valeur de la commande hors pourboire — le montant que rapportent les conversions), paymentMethod, servedBy, conversionId, createdAt, paidAt et attribution. Les montants sont toujours exprimés en unités mineures.

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

L’objet fidélité

Chaque événement, carte et récompense de fidélité partage un format unique : kind ("loyalty"), id (la carte), timezone, company, branch (le lieu de l’événement, s’il y en a un), program (id, name, stampsRequired, rewardTitle), customer (id, name, phone, locale), card (id, status, stampsCount, stampsRequired, stampsToReward, createdAt), stamp (pour un tampon : source, issuedBy, createdAt) et reward (pour une récompense : code, title, status, expiresAt, redeemedAt, redeemedBy), plus conversionId, l’identifiant sous lequel une inscription au programme de fidélité est rapportée.

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

Flux d’événements

Chaque ligne a la forme { id, cursor, type, createdAt, previousStatus, data }. data contient le sujet sous la clé indiquée par le préfixe de l’événement : data.booking, data.order ou data.loyalty. Conservez le cursor le plus élevé que vous avez traité et renvoyez-le dans after — il ne saute ni ne répète jamais une ligne, vous pouvez donc reprendre sans risque après une panne. Ignorez les types que vous ne gérez pas : de nouveaux types peuvent être ajoutés.

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

Webhooks

Créez un endpoint dans Intégrations → Webhooks et API — ou connectez Zapier, Make, n8n ou Pipedream dans Intégrations → Automatisation — pour que TapTime envoie en POST un événement JSON signé dès qu’une réservation, une commande ou une carte de fidélité change. Vous choisissez les événements pour chaque endpoint. Une entreprise peut disposer au total de 50 webhooks, postbacks, chats et connexions d’automatisation.

• Toute réponse 2xx est considérée comme livrée ; une réponse non 2xx ou un délai dépassé est réessayé avec un intervalle croissant (1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h) jusqu’à 8 tentatives — une réponse 410 arrête les nouvelles tentatives.
• Les redirections ne sont pas suivies.
• L’URL doit être en HTTPS en production et ne peut pas pointer vers une adresse privée ou de bouclage.
• La livraison est garantie au moins une fois : vérifiez toujours la signature et dédoublonnez sur 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));

Abonnements webhook

Les plateformes d’automatisation activent et désactivent les déclencheurs via l’API au lieu de demander à l’utilisateur de coller une URL (« REST hooks ») : envoyez en POST l’URL propre à la plateforme avec les événements souhaités, conservez l’id renvoyé, et supprimez-le avec DELETE lorsque le déclencheur est désactivé. Un abonnement est un webhook signé ordinaire — il apparaît dans le panneau de gestion, marqué de la clé qui l’a créé.

• Une clé ne voit et ne supprime que les abonnements qu’elle a créés ; la révocation de la clé les supprime tous.
• Les adresses sur hooks.zapier.com, make.com et pipedream.net sont reconnues et affichées avec le nom de la plateforme ; toute autre adresse https est un webhook classique.
• Le secret de signature est renvoyé une seule fois, dans la réponse au POST ; le propriétaire peut l’afficher à nouveau dans le panneau de gestion.

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

Une requête GET ou POST vers l’URL de votre propre outil de suivi avec les macros remplies, pour les plateformes qui utilisent des postbacks par chaîne de requête plutôt que des webhooks JSON. Pour une commande, {value} correspond à la valeur de la commande hors pourboire et {order_id} à son identifiant.

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

Variables disponibles

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

Erreurs

Chaque erreur est renvoyée en JSON : { "error": "<code>", "message": "<texte lisible>" }.