Introduction

L’API Service est une API HTTP en lecture seule pour les réservations et les clients de votre restaurant. Elle est gratuite et actuellement en bêta.

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 et automatisations — qui souhaitent un accès programmatique à leurs propres données de réservation et de clients.

Accès bêta — quelques limitations

• Les clés sont fournies sur demande, pas encore en libre-service — demandez-en une et nous la générons pour votre restaurant.
• Les points de terminaison de webhook sont eux aussi fournis sur demande (voir Webhooks).
• Pas de bac à sable public. Il existe une seule URL de base de production et les clés sont en production ; l’API est en lecture seule, donc les appels ne modifient jamais vos données.
• Pas encore de déclencheur de test de webhook en libre-service. Comme l’API est en lecture seule, vous ne pouvez pas créer ou modifier un enregistrement pour déclencher un événement à la demande ; les webhooks se déclenchent à partir de l’activité réelle du restaurant.

URL de base

Toutes les requêtes sont adressées à un hôte 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
GET https://api.useservice.app/v1/guests

Ce que vous pouvez faire

• 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.
• 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.
• Webhooks — abonnez-vous à des événements signés et en temps réel pour le cycle de vie des réservations ainsi que les événements liés aux clients et aux avis. Voir Webhooks.

L’écriture de données (création ou modification de réservations et de clients) ne fait pas partie de cette version.

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
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

1. Lisez Authentification et obtenez une clé.
2. Parcourez Pagination et Erreurs.
3. 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.
4. Configurez les Webhooks pour réagir aux changements en temps réel.