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 (du plus récent au plus ancien), 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.
`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 ou /v1/guests 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`	Un identifiant de ressource (`resv_…` / `gst_…`). Renvoie la page de résultats après cet objet.
`ending_before`	Un identifiant de ressource. Renvoie la page de résultats avant cet objet.

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 ou GET /v1/guests. 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.