Introduction

L’API Service est une API HTTP pour les réservations et les clients de votre restaurant. Vous pouvez les lire, et vous pouvez réserver, poser une option, modifier et annuler.

Les mots de la restauration que ce site emploie sans cérémonie — un couvert, un service, une limite de service, une réservation publiée — sont définis dans le Glossaire.

Elle est conçue pour les restaurants et les outils qu’ils utilisent — sites web sur mesure, tableaux de bord internes, CRM, pipelines d’analyse, automatisations et tunnels de réservation construits sur Service — qui souhaitent un accès programmatique à leurs propres données de réservation et de clients.

Configuration en libre-service. Créez vos clés d’API et enregistrez vos points de terminaison de webhook vous-même depuis le back-office (Paramètres → Développeurs) — aucune demande nécessaire.
Ce qu’une clé peut faire est choisi à sa création. Une nouvelle clé lit et rien d’autre ; réserver, passer outre une règle et lire les clients sont des portées distinctes que le restaurant accorde une par une.
Pas de bac à sable public. Il existe une seule URL de base de production et toutes les clés sont en production. Une réservation que vous créez est réelle, et une annulation aussi — il n’y a nulle part où la répéter, sinon sur un restaurant qui vous appartient.
Les écritures déclenchent des webhooks. Une création ou une annulation émet les mêmes événements qu’une réservation prise dans le back-office : votre propre appel peut donc être ce qui exerce votre gestionnaire.

URL de base

Toutes les requêtes sont adressées à un domaine unique et dédié, en HTTPS :

https://api.useservice.app

Chaque point de terminaison se trouve sous le préfixe de chemin stable /v1, par exemple :

GET  https://api.useservice.app/v1/reservations
POST https://api.useservice.app/v1/reservations
GET  https://api.useservice.app/v1/guests

Ce que vous pouvez faire

Réserver — créez une réservation, modifiez-la, annulez-la. Chaque création porte une Idempotency-Key, pour qu’une nouvelle tentative après un délai dépassé retrouve la même réservation au lieu d’en créer une deuxième.
Poser une option sur un créneau — retirez une table de la vente le temps qu’un client paie ou se décide, puis convertissez l’option en réservation ou rendez-la. Une option n’est pas une réservation et ne figure pas parmi elles.
Réservations — listez et filtrez les réservations, récupérez une réservation unique (avec ses affectations de tables et son client), et lisez l’historique des événements du cycle de vie d’une réservation.
Disponibilités et politique — demandez quels horaires sont réservables à une date ou sur un mois, lisez les règles de réservation du restaurant et listez ses sections.
Clients — listez et recherchez des clients par téléphone, e-mail ou requête en texte libre, et récupérez un client unique avec ses coordonnées, ses indicateurs de consentement et ses statistiques de visite.
Liste d’attente — lisez la file des clients qui attendent une table. Elle est en lecture seule : on y entre depuis le widget ou le back-office, pas d’ici.
Webhooks — abonnez-vous à des événements signés et en temps réel pour le cycle de vie des réservations, les options, ainsi que les événements liés aux clients et aux avis. Voir Webhooks.

Les clients sont en lecture seule. Une réservation que vous créez nomme son client, et Service retrouve ou crée la fiche correspondante ; aucun point de terminaison ne modifie directement un client.

Les conventions en un coup d’œil

Domaine	Convention
Transport	HTTPS uniquement, corps de requête/réponse en JSON
Authentification	`Authorization: Bearer sk_live_…` — une clé d’API par restaurant
Versionnement	En-tête `Service-Version` basé sur la date, épinglé à chaque clé
Identifiants	Chaînes opaques préfixées (`resv_…`, `gst_…`) — ne présumez d’aucun format au-delà du préfixe
Horodatages	ISO-8601 avec le décalage UTC du restaurant (par ex. `2026-06-27T19:30:00+02:00`)
Listes	`{ "object": "list", "data": [...], "has_more": true }` — voir Pagination
Erreurs	`{ "error": { "type", "code", "message", "param"?, "doc_url" } }` (`param` uniquement lorsqu’un paramètre est en cause) — voir Erreurs
Écritures	`Idempotency-Key`, exigée à chaque création et facultative ailleurs — voir Erreurs
Permissions	Portées par clé, accordées à la création et jamais élargies
Objets	Chaque ressource porte un champ `object` (`"reservation"`, `"guest"`, `"list"`, …)

Structure des réponses

Les ressources uniques sont renvoyées sous forme d’objet JSON plat avec un discriminateur object :

{
  "object": "reservation",
  "id": "resv_8xKQ2m4Vd0pErJ7sN1aZ9bQ",
  "status": "confirmed",
  "party_size": 4,
  "service_date": "2026-06-27",
  "starts_at": "2026-06-27T20:00:00+02:00",
  "created_at": "2026-06-20T11:04:18+02:00",
  "updated_at": "2026-06-25T09:12:55+02:00"
}

Les collections sont encapsulées dans une enveloppe de liste :

{
  "object": "list",
  "data": [ { "object": "reservation", "id": "resv_…" } ],
  "has_more": true
}

Étapes suivantes

Lisez Authentification, choisissez les portées qu’il vous faut et obtenez une clé.
Parcourez Pagination et Erreurs — la page des erreurs couvre aussi l’idempotence et la forme d’une réservation refusée.
Suivez un cas d’usage de bout en bout : Construire un tunnel de réservation va des disponibilités jusqu’à la création, et Poser une option couvre la rétention d’une table pendant qu’un package s’assemble. Trois autres vont plus loin : Réserver malgré les règles, Garder votre système synchronisé et Demander une garantie par carte.
Explorez la référence de l’API complète (en anglais), ou récupérez la spécification OpenAPI pour générer un SDK ou l’importer dans Postman.
Configurez les Webhooks pour réagir aux changements en temps réel.