Skip to main content
Cette page rassemble les recommandations à suivre pour une intégration robuste, performante et sûre de Le Commis. Parcourez-la comme une checklist avant de passer en production.
Deux réflexes couvrent l’essentiel : indexer vos lectures sur content_revision (vous évitez les téléchargements inutiles, image, PDF ou Carte unifiée) et préférer les webhooks au polling (vous préservez vos quotas de requêtes). Le reste de cette page détaille les points plus fins.

​
Checklist rapide

Clé d’API utilisée uniquement côté serveur, jamais exposée au client.
Réponses mises en cache et indexées sur content_revision.
Clé de cache déclinée par locale (fr / en).
Champs nullable gérés explicitement dans le code.
Prix lus comme des chaînes de caractères, pas des nombres.
Webhooks rendus idempotents via X-LeCommis-Delivery.
Signature HMAC des webhooks vérifiée à temps constant.
Réponse 2xx rapide au webhook, traitement en asynchrone.
Webhooks préférés au polling de l’API.
Backoff appliqué sur les réponses 429.

​
Détails

La clé d’API est un secret serveur-à-serveur. Appelez toujours Le Commis depuis votre backend et stockez la clé dans une variable d’environnement ou un gestionnaire de secrets. Ne l’embarquez jamais dans du JavaScript de navigateur, une application distribuée ou un dépôt public.

Authentification

Détails sur la clé X-Api-Key et sa rotation.
Chaque ressource expose un entier monotone content_revision, identique pour tout l’établissement. Stockez la dernière valeur connue ; ne re-téléchargez le contenu que lorsqu’elle augmente. C’est le mécanisme recommandé d’invalidation de cache.

content_revision

Le compteur de révision pour détecter les changements.
content_revision est commun à toutes les langues : la même valeur couvre fr et en. En revanche, le contenu des menus diffère selon la locale. Intégrez donc la locale dans votre clé de cache, par exemple au-bistrot:menus:fr:rev67 et au-bistrot:menus:en:rev67. Une seule notification de changement invalide les deux langues.

Comportement de fallback i18n

Traductions, fallback en vers fr et portée des fichiers du menu (champ assets).
De nombreux champs peuvent être null : description, category, website_url, menu_url, l’email et le téléphone de contact, les coordonnées de localisation, logo_url, master_menu_url (l’URL de la Carte unifiée), reference_date, le price d’un item, etc. Prévoyez systématiquement une valeur de repli ou un affichage conditionnel plutôt que d’afficher null ou de planter.
Le price d’un item est sérialisé en chaîne décimale ("12.50") et vaut null hors des items à la carte. Ne le convertissez pas naïvement en flottant si vous devez préserver l’exactitude monétaire ; conservez-le tel quel pour l’affichage et utilisez un type décimal pour les calculs.
Un même événement peut être livré plusieurs fois (retries après timeout réseau). Utilisez l’en-tête X-LeCommis-Delivery (identifiant unique de livraison) comme clé d’idempotence : enregistrez les identifiants déjà traités et ignorez les doublons.

Webhooks

Cycle de vie des livraisons et retries.
Chaque webhook est signé. Reconstituez signed_payload = "{X-LeCommis-Timestamp}.{corps brut}", calculez HMAC_SHA256(signing_secret, signed_payload) en hexadécimal préfixé sha256=, et comparez à X-LeCommis-Signature à temps constant. Rejetez aussi les requêtes dont le timestamp s’écarte de plus de quelques minutes pour vous protéger du rejeu.

Sécurité des webhooks

Vérification de signature et tolérance d’horloge.
Le succès d’une livraison est défini par une réponse 2xx. Répondez immédiatement (accusé de réception) puis effectuez le travail lourd (re-fetch de l’API, purge de cache, rebuild) en tâche de fond. Une réponse lente peut provoquer un timeout côté Le Commis et déclencher un retry inutile.
N’interrogez pas l’API en boucle pour détecter un changement : vous épuiseriez vos quotas. Laissez le webhook establishment.content_updated vous signaler quand re-lire l’API, et limitez-vous aux ressources listées dans changed_resources.
En cas de 429 Rate limit exceeded, attendez avant de réessayer, avec un délai croissant (backoff exponentiel) et un peu de jitter. N’enchaînez pas les tentatives immédiates.

Quotas de requêtes

Quotas et stratégie de backoff.