# Démarrage rapide

> D'une clé à vos premiers enregistrements et à une photographie de livraison en cinq minutes, avec curl.

Source: https://developers.backresto.com/fr/docs/quickstart

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](mailto:contact@backresto.com?subject=Partner%20API%20key%20request)
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é](https://developers.backresto.com/fr/docs/access) 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.

```bash
export BACKRESTO_PARTNER_API_KEY='brp_…'
```

## 3. Trouver votre restaurant

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

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

```json
{
  "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 :

```bash
export RESTAURANT_ID='restaurant-1'
```

## 4. Voir quelles collections la clé ouvre

Chaque type d'enregistrement, livraisons comprises, est une
[collection](https://developers.backresto.com/fr/docs/collections). Demandez à la clé lesquelles elle atteint :

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

```json
{
  "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](https://developers.backresto.com/fr/docs/access).

## 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.

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

```json
{
  "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 :

```bash
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](https://developers.backresto.com/fr/docs/errors), 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é](https://developers.backresto.com/fr/docs/access) : la liste de contrôle de la demande, et comment modifier une clé plus tard.
- [Authentification](https://developers.backresto.com/fr/docs/authentication) : les scopes, la rotation, ce qu'une clé peut et ne peut pas faire.
- [Pagination](https://developers.backresto.com/fr/docs/pagination) : le curseur, et comment maintenir une copie à jour.
- [Livraisons](https://developers.backresto.com/fr/docs/deliveries) : chaque champ d'un contrôle à réception et de ses photographies.
- [Collections et enregistrements](https://developers.backresto.com/fr/docs/collections) : les vingt-six types d'enregistrement, et l'enveloppe qu'ils partagent.
- [MCP](https://developers.backresto.com/fr/docs/mcp) : les mêmes données dans un client IA, en trois minutes environ.