Démarrage rapide

Il vous faut une seule chose : une clé partenaire. Elle sait déjà quels restaurants lui ont été accordés, et l'API vous le dit.

1. Obtenir une clé

Écrivez à contact@backresto.com avec votre société, les restaurants dont vous avez besoin et les scopes que vous voulez. Nous confirmons auprès du restaurant, puis envoyons la clé au contact technique que vous avez nommé. Obtenir une clé est la liste de contrôle complète : l'envoyer complète est ce qui fait de l'aller-retour un e-mail plutôt que quatre.

Une clé ressemble à ceci :

brp_hV8kZ2pQ.tW3nR7yL9cF1sB4xJ6mA8dK0gN5vE2uP7hQ3rT1zY6i

La moitié avant le point est un préfixe public : il identifie la clé dans la liste sur cette page et dans les échanges avec le support, et on peut l'écrire sans risque. La moitié qui suit est le secret, et il n'apparaît nulle part ailleurs que sur cet unique écran.

2. La stocker

Mettez la valeur entière dans votre gestionnaire de secrets, en une seule chaîne de caractères, et supprimez l'e-mail dans lequel elle est arrivée. Jamais un dépôt, jamais une URL, jamais une ligne de journal. Nous ne conservons qu'une empreinte du secret, donc une clé perdue veut dire une révocation et une nouvelle clé. Écrivez-nous et les deux ont lieu le jour même.

export BACKRESTO_PARTNER_API_KEY='brp_…'

3. Trouver votre restaurant

Demandez à la clé quels restaurants elle atteint, et avec quels scopes :

curl "https://api.backresto.com/v1/restaurants" \
  -H "Authorization: Bearer $BACKRESTO_PARTNER_API_KEY"

{
  "data": [
    {
      "restaurantId": "restaurant-1",
      "scopes": ["deliveries:read", "delivery-pictures:read", "temperature-records:read"]
    }
  ]
}

La plupart des clés atteignent un seul restaurant. Gardez son identifiant pour les appels suivants :

export RESTAURANT_ID='restaurant-1'

4. Voir quelles collections la clé ouvre

Chaque type d'enregistrement, livraisons comprises, est une collection. Demandez à la clé lesquelles elle atteint :

curl "https://api.backresto.com/v1/restaurants/$RESTAURANT_ID/collections" \
  -H "Authorization: Bearer $BACKRESTO_PARTNER_API_KEY"

{
  "data": [
    {
      "collection": "deliveries",
      "readScope": "deliveries:read",
      "description": "Received shadow snapshots for deliveries; not complete primary-store history.",
      "stateKind": "received-shadow-snapshot",
      "payloadVersion": 1
    }
  ]
}

Un data vide signifie que la clé n'a encore aucune autorisation sur les collections. Demandez celles dont vous avez besoin.

5. Parcourir les livraisons

Une collection se parcourt page par page avec un curseur opaque. Les horodatages sont en millisecondes depuis l'epoch, sous forme de chaînes de caractères : c'est la convention dans toute l'API, jamais des secondes, jamais de l'ISO 8601.

curl "https://api.backresto.com/v1/restaurants/$RESTAURANT_ID/collections/deliveries/records" \
  -H "Authorization: Bearer $BACKRESTO_PARTNER_API_KEY" \
  --get --data-urlencode "limit=100"

{
  "data": [
    {
      "id": "8f2c1b04-0d5a-4b7e-9f31-6ad2c0e77a51",
      "restaurantId": "restaurant-1",
      "collection": "deliveries",
      "deleted": false,
      "capturedAt": "1787932805120",
      "receivedAt": "1787932911004",
      "sequence": "88",
      "data": {
        "timestamp": "1787932800000",
        "isCompliant": false,
        "supplierDeliveriesId": "supplier-7",
        "temperatureRecords": [
          { "product": "Poulet fermier", "lotNumber": "L2291", "value": 6.4, "unit": "C" }
        ],
        "nonComplianceReasons": ["Température trop élevée"],
        "correctiveActions": ["Produit refusé"],
        "commentary": null
      }
    }
  ],
  "nextCursor": null
}

Les températures sont toujours en degrés Celsius. Pas de plage de temps ici : vous parcourez la collection, vous filtrez sur data.timestamp si vous voulez une semaine, et vous gardez id pour réconcilier au parcours suivant. Les autres collections (températures, refroidissement, nettoyage, étiquettes) se parcourent exactement de la même façon.

6. Récupérer les photographies d'une livraison

Les photographies sont la collection delivery-pictures. Chaque enregistrement nomme sa livraison dans data.deliveryId, et les octets viennent de ses fichiers :

curl "https://api.backresto.com/v1/restaurants/$RESTAURANT_ID/collections/delivery-pictures/records" \
  -H "Authorization: Bearer $BACKRESTO_PARTNER_API_KEY" \
  --get --data-urlencode "limit=100"

curl "https://api.backresto.com/v1/restaurants/$RESTAURANT_ID/collections/delivery-pictures/records/$PICTURE_ID/assets" \
  -H "Authorization: Bearer $BACKRESTO_PARTNER_API_KEY"

Le second appel répond par des URL signées valables quinze minutes ; téléchargez les octets sans en-tête Authorization. Il exige le scope delivery-pictures:read. Si votre clé n'a que deliveries:read, les livraisons répondent et les photographies répondent 403 : c'est l'autorisation qui fait son travail, et le remède est que le client fasse émettre une clé avec les deux.

7. Gérer les deux échecs que vous rencontrerez vraiment

404 : le restaurant n'est pas sur votre clé, ou l'enregistrement n'existe pas. Les deux sont volontairement indiscernables : l'API ne confirme pas l'existence d'un restaurant à un appelant qui ne peut pas le voir.

403 : le restaurant est sur votre clé, mais pas le scope dont cet endpoint a besoin.

Chaque erreur est un document problème, jamais une page HTML, et porte un requestId qu'il vaut la peine de citer si vous nous écrivez.

Où aller ensuite

• Obtenir une clé : la liste de contrôle de la demande, et comment modifier une clé plus tard.
• Authentification : les scopes, la rotation, ce qu'une clé peut et ne peut pas faire.
• Pagination : le curseur, et comment maintenir une copie à jour.
• Livraisons : chaque champ d'un contrôle à réception et de ses photographies.
• Collections et enregistrements : les vingt-six types d'enregistrement, et l'enveloppe qu'ils partagent.
• MCP : les mêmes données dans un client IA, en trois minutes environ.