> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eat-now.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Parcours de réservation

> Consulter les disponibilités, créer puis gérer une réservation.

## 1. Lire le catalogue

Avec `CATALOG_READ`, récupérez les identifiants des salles, services, tables,
prescripteurs et remises du restaurant. Le catalogue ne décrit pas les créneaux
réservables : il peut inclure des tables internes ou des remises inactives.
C’est la disponibilité qui détermine ce qui peut être réservé.

## 2. Chercher un créneau

Avec `AVAILABILITY_READ`, appelez `GET /availability` avec `start_at_from`,
`start_at_to` et `party_size`. Les filtres `shift_id` et `room_id` sont
facultatifs. Utilisez des dates ISO 8601 avec décalage explicite.
`--data-urlencode` conserve le signe `+` du décalage dans les paramètres de
l’URL.

```bash theme={null}
curl --get 'https://app.eat-now.io/api/partner/v1/availability' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  --data-urlencode 'start_at_from=2030-05-20T18:00:00+02:00' \
  --data-urlencode 'start_at_to=2030-05-20T23:00:00+02:00' \
  --data-urlencode 'party_size=2'
```

Dates, décalages et identifiants sont illustratifs. Reprenez `start_at`,
`shift_id` et la salle, si présente, d’un créneau réellement retourné. La
réponse fournit également `end_at` et `duration_minutes`.
`POST /availability/check` vérifie un seul créneau : `200` avec
`data.available: false` est un résultat indisponible normal.

La consultation ne bloque aucune capacité. La création revérifie le créneau et
peut répondre `422` s’il n’est plus réservable.

## 3. Créer la réservation

Appelez `POST /reservations` avec `RESERVATIONS_WRITE`. Voici un corps JSON ;
remplacez le créneau d’exemple par un résultat de disponibilité.

```json theme={null}
{
  "customer": { "name": "Client exemple", "email": "guest@example.com" },
  "party_size": 2,
  "start_at": "2030-05-20T19:00:00+02:00",
  "shift_id": "REPLACE_WITH_SHIFT_ID",
  "external_id": "your-system-booking-123",
  "send_client_notifications": false,
  "send_payment_link": false
}
```

Ces deux options d’envoi valent `true` par défaut. Les désactiver supprime les
notifications client et l’envoi du lien de paiement, sans simuler la
réservation, supprimer la création de paiements ni désactiver les notifications
du restaurant.

`customer: null` crée une réservation anonyme. Sinon, `customer.name` est requis
à la création. `source` vaut `WEBSITE` par défaut. Les exigences d’empreinte
bancaire peuvent être déduites du service ; le choix explicite de produits
prépayés ou d’extras n’est pas pris en charge en v1. Lisez le statut et les
paiements retournés : `201` ne garantit pas une confirmation.
`total_amount_paid` enregistre un montant en unité monétaire minimale, sans
débiter le client. Les options de contournement et `initial_status` sont
détaillées dans les [scopes](/fr/api-reference/authentication) et l’endpoint de
création.

### Reprendre après un résultat incertain

`external_id` doit être unique par restaurant. Un doublon renvoie `409`, pas la
réponse initiale. Après un timeout, cherchez `GET /reservations` par
`external_id` avec `RESERVATIONS_READ` avant de recréer. Gardez la même
référence externe. L’API ne propose pas de contrat d’en-tête `Idempotency-Key`.

## 4. Lire et modifier

`GET /reservations` accepte des filtres et une pagination : `page` commence à 1,
`per_page` vaut 25 par défaut et ne dépasse pas 100. `GET /reservations/{id}`
retourne le détail. Les deux exigent `RESERVATIONS_READ`, avec le scope
supplémentaire pour les données sensibles.

`PATCH /reservations/{id}` exige `RESERVATIONS_WRITE`. Les champs omis sont
conservés. `customer: null` détache le client ; `{ "id": "..." }` rattache un
client existant du restaurant. Des champs client sans identifiant modifient la
fiche liée elle-même, ce qui peut affecter les autres réservations du même
client. Si aucun client n’est lié, fournissez son nom pour en créer un et le
rattacher.

Les verrouillages de service POS peuvent refuser une modification avec `409` et
`details.locked_fields`. Les règles métier peuvent produire `422`. L’annulation
dispose d’un endpoint distinct.

## 5. Annuler

Appelez `POST /reservations/{id}/cancel` avec `RESERVATIONS_CANCEL`, le type de
contenu JSON et un corps JSON : `{}` ou `{ "reason": "Demande du client" }`. Le
statut devient `CANCELED_BY_RESTAURANT`. Une réservation déjà annulée est
retournée sans changer son statut ni son motif existants. Un verrouillage de
service POS peut refuser l’annulation avec `409`.

## 6. Recevoir des événements

Consultez la [référence webhooks](/fr/api-reference/webhooks) pour les
signatures, payloads et limites de couverture. Les écritures par API partenaire
n’émettent pas directement ces webhooks : n’attendez pas un webhook pour valider
votre écriture API.