Réservations

Étape 3 : bloquer une table (créer une réservation)

Dès qu'une réservation est validée dans votre système, envoyez-la à Belive.

POST /v1/reservations
Content-Type: application/json

{
  "tableId": "27ced4e4-c115-41b5-af27-93a7bd57cbcc",
  "date": "2026-10-16",
  "slot": "21:30",
  "guests": 4,
  "customer": { "name": "Yasmine Alaoui", "email": "yasmine@example.com", "phone": "+212600000001" },
  "notes": "Anniversaire",
  "externalRef": "LACALE-4421",
  "idempotencyKey": "lacale-4421-v1",
  "notifyCustomer": true
}

Réponse 201 :

{
  "beliveReservationId": "1e72349e-…",
  "accessCode": "BLV-T2VS",
  "status": "confirmed",
  "guestAccessUrl": "https://app.belive360.com/access/<jeton>",
  "claimUrl": "https://app.belive360.com/claim-guest/<jeton>",
  "accessLinkExpiresAt": "2026-10-18T06:00:00.000Z",
  "notifications": { "email": "sent", "sms": "skipped" }
}

Ce que vous devez faire de la réponse :

Stockez beliveReservationId et accessCode avec votre réservation. Vous en aurez besoin pour annuler et pour le contrôle d'accès.
Affichez accessCode sur votre propre confirmation (email, SMS, application). C'est ce code que le personnel peut rechercher dans Belive Terminal si le client n'a pas son QR.
Si vous préférez envoyer vous-même la confirmation au client, passez notifyCustomer: false et intégrez guestAccessUrl dans votre message. Sinon Belive envoie l'email.

Règles importantes :

customer.name est obligatoire, et customer.email ou customer.phone l'est aussi : c'est ce qui permet de créer le QR du client. Sans contact, la réservation est refusée (CUSTOMER_CONTACT_REQUIRED).
idempotencyKey est obligatoire. Utilisez votre identifiant de réservation, suffixé d'une version (lacale-4421-v1). Si votre appel est coupé et que vous le rejouez avec la même clé, Belive renvoie la même réservation en 200 avec l'en-tête Idempotent-Replayed: true. Aucun doublon n'est possible.
guests doit être compris entre capacityMin et capacityMax de la table, sinon GUESTS_OUT_OF_RANGE.
Les réservations partenaires sont créées en statut confirmed, sans paiement en ligne et sans commission.

Quand la table est déjà prise

HTTP 409
{ "error": "Cette table est déjà réservée pour ce créneau.", "error_en": "This table is already booked for this slot.", "code": "TABLE_TAKEN" }

La règle est « premier arrivé, premier servi ». Dans ce cas, refusez la réservation dans votre système ou proposez une autre table. Ne réessayez pas le même appel.

Créneau absent

Si vous n'envoyez pas de slot, la table est bloquée pour toute la date, sur tous les créneaux. C'est voulu pour les lieux sans service en deux temps, mais pour un restaurant avec deux services, envoyez toujours le créneau.

Étape 4 : annuler une réservation

DELETE /v1/reservations/1e72349e-…

{ "beliveReservationId": "1e72349e-…", "status": "cancelled", "cancelledAt": "2026-10-15T18:02:11.000Z" }

La table est libérée immédiatement et le lien d'accès du client cesse de fonctionner.
L'appel est idempotent : une seconde annulation renvoie 200 avec alreadyCancelled: true.
Vous ne pouvez annuler que les réservations créées avec votre clé. Une réservation prise sur Belive 360 renvoie 404 NOT_FOUND : elle s'annule depuis le portail vendeur ou par le client.

Étape 5 : lire les réservations Belive

Pour afficher dans votre outil les réservations prises sur Belive 360 (ou pour un rapprochement quotidien) :

GET /v1/reservations?from=2026-10-16&to=2026-10-16&status=confirmed,completed&page=1&limit=50

{
  "items": [
    { "id": "…", "accessCode": "BLV-S8Z9", "status": "completed", "date": "2026-10-16", "slot": "21:30",
      "table": { "id": "27ced4e4-…", "name": "Table 9" }, "guests": 3, "customerFirstName": "Othmane",
      "source": "belive", "checkedInAt": null, "createdAt": "2026-10-10T12:00:00.000Z" }
  ],
  "page": 1, "limit": 50, "total": 1, "contactDetailsIncluded": false
}

Statuts à connaître :

Statut	Signification	Bloque la table ?
`confirmed`	Confirmée (réservation partenaire, ou demande acceptée en mode sans paiement)	Oui
`completed`	Payée sur Belive 360	Oui
`requested`	Demande en attente de réponse de l'établissement (mode sans paiement)	Oui
`pending`, `partial`	Paiement en cours sur Belive 360	Oui, temporairement
`cancelled`, `declined`	Annulée ou refusée	Non

Données client : par défaut vous recevez le prénom et le nombre de couverts. L'email et le téléphone ne sont inclus (contactDetailsIncluded: true) que si l'établissement est en mode « sans paiement », parce qu'il doit alors pouvoir rappeler le client. externalRef n'est renvoyé que pour vos propres réservations.

Préférez les webhooks (§7) au polling : ils sont plus rapides et ne consomment pas votre quota.