Référence

Authentification et conventions

Tout ce qui s'applique à chaque point de terminaison : comment s'authentifier, les limites et la structure des réponses.

Authentification

Chaque requête comporte un en-tête Authorization: Bearer avec une clé que vous générez dans votre tableau de bord. Les clés ressemblent à oac_live_…, sont limitées à votre entreprise et ne sont affichées qu'une seule fois à leur création — conservez-les en lieu sûr. Une clé manquante, mal formée ou révoquée renvoie un 401.

Authorization: Bearer oac_live_3f9a…c1e7

Chaque lecture est automatiquement limitée aux restaurants de votre entreprise — vous ne pouvez jamais voir les données d'un autre locataire, même en devinant un identifiant. Générez ou révoquez des clés dans Clés d'API.

Limites de débit

60 requêtes par minute et par clé d'API. Chaque réponse indique le budget actuel ; les requêtes au-delà de la limite reçoivent un 429 avec un en-tête Retry-After (en secondes).

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 41
X-RateLimit-Reset: 1734556800
Retry-After: 17          # only on 429

Besoin d'un plafond plus élevé pour une synchronisation en masse ? Contactez-nous.

Erreurs

Les erreurs utilisent les codes de statut HTTP standard et un corps JSON contenant un champ error lisible par un humain.

{ "error": "Restaurant not found" }

Statut	Signification
200 / 201	Succès. Les requêtes POST qui créent une ressource renvoient 201.
400	Requête mal formée — JSON incorrect ou champs invalides/manquants.
401	Clé d'API manquante, mal formée ou révoquée.
404	Ressource introuvable ou n'appartenant pas à votre entreprise.
409	Conflit — réservations désactivées ou créneau complet.
429	Limite de débit dépassée. Patientez en respectant Retry-After.
5xx	Erreur serveur transitoire — réessayez avec un délai progressif.

Pagination

Les points de terminaison de liste sont paginés par curseur. Transmettez limit (par défaut 50, max 100) et suivez nextCursor jusqu'à ce qu'il vaille null. Ne vous fiez jamais aux décalages.

Parcourir toutes les réservations

let cursor = null;
do {
  const url = new URL("https://openalacarte.com/api/v1/bookings");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);
  const { data, nextCursor } = await (await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.OAC_API_KEY}` },
  })).json();
  handle(data);
  cursor = nextCursor;
} while (cursor);

Versionnage et stabilité

L'API est versionnée dans l'URL (/api/v1/…). Les changements incompatibles sont publiés en tant que v2 aux côtés de la v1.
La v1 reste disponible pendant au moins 12 mois après tout avis de dépréciation.
Les changements additifs (nouveaux champs, points de terminaison, événements de webhook) ne sont pas incompatibles — tolérez les champs inconnus.
Tous les horodatages sont au format ISO-8601 en UTC.

Générez un SDK typé ou importez dans Postman à partir de la spécification OpenAPI 3.0.