Pagination

Les points de terminaison de liste sont paginés par curseur. Les curseurs sont stables et performants même sur de grands volumes de données, et il n’y a délibérément aucun décompte total.

Enveloppe de liste

Chaque réponse de liste a la même structure :

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

• data — la page de résultats.
• has_more — true s’il existe d’autres résultats après cette page.

Il n’y a pas de total_count : calculer un total exact est coûteux et sujet aux conditions de course sur des données en direct. Paginez jusqu’à ce que has_more soit false.

Ordre par défaut

Sans updated_since, chaque point de terminaison de liste possède un tri par défaut stable, avec l’identifiant de la ressource comme départage afin que le curseur keyset soit total :

Point de terminaison	Ordre par défaut
GET /v1/reservations	par service_date décroissant, puis id décroissant — les dates de service les plus récentes d’abord. Pour une même date de service, les réservations suivent leur ordre de création, la plus récente d’abord, et non l’ordre de start_time.
GET /v1/holds	par created_at décroissant, puis id décroissant — les options posées le plus récemment d’abord.
GET /v1/waitlist-entries	par created_at décroissant, puis id décroissant — les entrées créées le plus récemment d’abord.
GET /v1/guests	par created_at décroissant, puis id décroissant — les clients créés le plus récemment d’abord.
GET /v1/reservations/{id}/events	par created_at croissant, puis id croissant — l’événement le plus ancien d’abord (chronologique).

Passer updated_since à /v1/reservations, /v1/guests ou /v1/waitlist-entries change le tri en (updated_at, id) croissant (voir ci-dessous), de sorte qu’un flux « modifié depuis » se lit du changement le plus ancien au plus récent.

Paramètres

Paramètre	Description
limit	Taille de page. Valeur par défaut 20, maximum 100. (Lorsque vous étendez des objets, le maximum est abaissé.)
starting_after	L’identifiant d’une ressource de la liste (resv_…, hold_…, wl_…, gst_…, evt_…). Renvoie la page de résultats après cet objet.
ending_before	L’identifiant d’une ressource de la liste. Renvoie la page de résultats avant cet objet.

Un curseur est toujours l’id d’une ressource que vous avez reçue. Chaque point de terminaison de liste, liste des événements comprise, accepte les deux paramètres.

Utilisez l’identifiant du dernier élément d’une page comme starting_after pour récupérer la page suivante :

# First page
curl "https://api.useservice.app/v1/reservations?limit=20" \
  -H "Authorization: Bearer $SERVICE_API_KEY"

# Next page — pass the last id you saw
curl "https://api.useservice.app/v1/reservations?limit=20&starting_after=resv_8xKQ2m4Vd0pErJ7sN1aZ9bQ" \
  -H "Authorization: Bearer $SERVICE_API_KEY"

Continuez tant que has_more vaut true.

Filtrage

Les points de terminaison de liste acceptent des filtres en plus des paramètres de pagination (voir la référence de l’API (en anglais) pour l’ensemble complet par point de terminaison). Quelques règles de correspondance à connaître :

• email (clients) est mis en correspondance sans tenir compte de la casse comme une adresse exacte — [email protected] et [email protected] renvoient le même client.
• phone (clients) est normalisé au format E.164 avant la correspondance, en utilisant le pays du restaurant. Transmettez le numéro tel que le client l’a fourni (local ou international) ; il est canonicalisé avant la recherche.
• query (clients) est une correspondance de sous-chaîne insensible aux accents portant sur le prénom, le nom et l’e-mail.

Les filtres se combinent avec un AND. Une valeur de filtre inconnue (par exemple un status inconnu ou une date mal formée) renvoie un 400 avec le param fautif — voir Erreurs.

Synchronisation incrémentale avec updated_since

Pour maintenir une copie locale à jour sans tout relire, passez updated_since (un horodatage ISO-8601) à GET /v1/reservations, GET /v1/guests ou GET /v1/waitlist-entries. Vous ne recevez en retour que les enregistrements modifiés à partir de cet instant, triés par (updated_at, id) croissant. Combinez-le avec la pagination par curseur comme d’habitude :

curl "https://api.useservice.app/v1/reservations?updated_since=2026-06-27T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $SERVICE_API_KEY"

À la synchronisation suivante, utilisez le updated_at le plus récent que vous avez vu comme nouveau updated_since.

Des lignes peuvent se répéter — concevez pour l’idempotence

Comme les enregistrements sont ordonnés par updated_at, un enregistrement qui change de nouveau pendant que vous paginez (ou entre deux synchronisations) peut apparaître plus d’une fois. Traitez le flux comme au moins une fois : faites un upsert par id afin que revoir un enregistrement soit sans conséquence. Utilisez un léger chevauchement (recommencez la requête un peu avant votre dernier horodatage) plutôt que de présumer une livraison exactement une fois.

Les statistiques sont instantanées, pas synchronisées

Les statistiques de client telles que visit_count, no_show_count et cancellation_count sont des valeurs calculées renvoyées au moment de la lecture. Elles ne font pas partie de la surface de synchronisation updated_since et ne déclenchent pas à elles seules un webhook guest.updated. Interrogez directement un client lorsque vous avez besoin de ses statistiques actuelles.