Support et exhaustivité des données

La réserve sur l'exhaustivité, dite simplement

L'API Partenaire expose les enregistrements saisis après l'activation de la fonctionnalité pour ce restaurant, dans chaque collection. Elle ne prétend pas détenir l'historique complet d'un restaurant, et elle n'en reconstituera pas un. Les livraisons sont la seule exception : leurs deux collections portent l'historique que l'application détenait encore à leur ouverture.

Cela compte davantage qu'il n'y paraît :

• Un résultat vide n'est pas la preuve que rien ne s'est passé. Cela peut vouloir dire que le restaurant n'était pas encore activé, ou qu'un appareil n'a pas encore téléversé.
• Un décompte issu de cette API n'est pas un chiffre de conformité. N'en imprimez pas un sur un rapport qui se lit comme un audit.
• Si vous avez besoin de connaître la date d'activation d'un restaurant, demandez-nous ou demandez au client. Elle n'est pas exposée par l'API aujourd'hui. Si vous en avez besoin comme champ, dites-le-nous et elle en deviendra un.

Les collections le disent dans leur propre réponse : stateKind vaut received-shadow-snapshot, c'est-à-dire l'état que cette API a reçu, pas l'état que détient l'application du restaurant. Les deux concordent dans le cas ordinaire et divergent exactement quand un appareil n'a pas encore téléversé.

Une fois un restaurant activé, les enregistrements arrivent de façon fiable, y compris ceux saisis pendant qu'un appareil était hors ligne : ceux-là sont téléversés à la reconnexion, et c'est pourquoi l'interrogation incrémentale doit se chevaucher et pourquoi capturedAt et receivedAt figurent tous les deux sur chaque enregistrement.

Versionnage

Tous les chemins sont préfixés par /v1, et cette API est en bêta fermée. Les clés sont délivrées à la main, à une poignée d'intégrateurs, et la forme de l'API n'est pas encore arrêtée. À prendre au pied de la lettre : à l'intérieur de /v1, tant que dure la bêta, un endpoint peut changer de forme ou être retiré, et nous ne promettons pas le contraire.

Ce que cela veut dire en pratique :

• Analysez avec souplesse. Ignorez les champs que vous ne connaissez pas plutôt que d'échouer dessus ; il s'en ajoute souvent.
• Surveillez les endpoints retirés. Les endpoints de livraison dédiés, et le scope qui ouvrait leurs photographies, n'existent plus : les livraisons se lisent comme des collections, comme tous les autres types d'enregistrement. Voir plus bas.
• Faites-vous connaître. Nous savons quelles clés nous ont appelés, et quand. Si la vôtre est utilisée, nous vous contacterons avant de déplacer quoi que ce soit dessous, non parce que la bêta nous y oblige, mais parce que casser par surprise une intégration qui marche est une mauvaise façon d'en mener une.

Quand la bêta prendra fin, cette section deviendra la promesse habituelle : des changements additifs à l'intérieur d'une version, tout le reste derrière /v2. Ce n'est pas encore le cas, et le dire vous est plus utile qu'une garantie que nous aurions à reprendre.

Le document OpenAPI est généré à partir du service en fonctionnement : c'est donc la description faisant autorité de ce qui est déployé en ce moment. Si cette documentation et ce document divergent, c'est le document qui a raison et nous avons une page à corriger. Dites-le-nous.

Contrôles de santé

Deux endpoints publics, sans authentification :

/health/ready est celui à interroger si vous nous supervisez. Les sondes réussies ne sont pas consignées au journal d'audit, une supervision n'ajoute donc pas de bruit.

Obtenir de l'aide

Écrivez à contact@backresto.com. Ce qui rend une réponse rapide :

• le requestId du document problème, ou le X-Request-ID que vous avez envoyé ;
• le préfixe public de votre clé, la moitié brp_… avant le point, jamais le secret ;
• l'environnement, l'endpoint, et à peu près quand.

Ne nous envoyez jamais le secret d'une clé : le préfixe public l'identifie sans ambiguïté. Si un secret est parti là où il n'aurait pas dû, dites-le dans l'objet du message et envoyez le préfixe : la révocation est immédiate, et c'est tout le remède. Voyez Obtenir une clé pour le reste du cycle de vie d'une clé.

Demander plus

Ce qui existe ici existe parce que quelqu'un l'a demandé. Les températures de cuisson et de refroidissement, les plans de nettoyage, les étiquettes et un endpoint MCP hébergé étaient tous sur cette liste il y a quelques mois ; ce sont aujourd'hui des collections et un endpoint.

Les livraisons étaient le dernier élément de cette liste. Elles ont été la première chose que cette API a servie, par leurs propres endpoints, avec leur propre forme et une plage de temps plutôt qu'un curseur. Ce sont désormais deux collections, deliveries et delivery-pictures, lues à travers la même enveloppe, la même pagination et le même GET .../collections/{collection}/records que tous les autres types d'enregistrement, et les anciens endpoints sont retirés plutôt que maintenus à côté. Une seule façon de lire un enregistrement, c'est tout l'objet du changement. Si vous avez construit sur les anciens endpoints, Livraisons montre la nouvelle forme, et nous vous aidons volontiers à migrer.

Ce qui y figure encore : des webhooks plutôt que de l'interrogation, un curseur incrémental sur les collections, une date d'activation sur le restaurant, et une connexion OAuth pour les clients MCP qui refusent une clé. Celle qui vient ensuite est décidée par ceux qui demandent. Alors demandez.