# Guida rapida

> Da una chiave ai suoi primi record e a una fotografia di consegna in cinque minuti, con curl.

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

Le serve una cosa sola: una chiave partner. Sa già quali ristoranti le sono
stati concessi, e l'API glielo dice.

## 1. Ottenere una chiave

Scriva a [contact@backresto.com](mailto:contact@backresto.com?subject=Partner%20API%20key%20request)
indicando la sua azienda, i ristoranti di cui ha bisogno e gli scope che
desidera. Confermiamo con il ristorante, poi inviamo la chiave al contatto
tecnico che ha indicato. [Ottenere una chiave](https://developers.backresto.com/it/docs/access) è la lista di
controllo completa: inviarla completa è ciò che riduce lo scambio a una email
invece che a quattro.

Una chiave si presenta così:

```
brp_hV8kZ2pQ.tW3nR7yL9cF1sB4xJ6mA8dK0gN5vE2uP7hQ3rT1zY6i
```

La metà prima del punto è un prefisso pubblico: identifica la chiave
nell'elenco su quella pagina e nelle conversazioni con il supporto, e può essere
annotata senza rischi. La metà dopo il punto è il secret, e non compare da
nessuna parte se non su quella singola schermata.

## 2. Conservarla

Metta l'intero valore nel suo gestore di secret, come una sola stringa, ed
elimini l'email con cui è arrivata. Mai in un repository, mai in un URL, mai in
una riga di log. Conserviamo solo un digest del secret, quindi una chiave persa
significa una revoca e una chiave nuova. Ci scriva e accadono entrambe in
giornata.

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

## 3. Trovare il suo ristorante

Chieda alla chiave quali ristoranti raggiunge, e con quali scope:

```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 maggior parte delle chiavi raggiunge un solo ristorante. Tenga il suo
identificativo per le chiamate seguenti:

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

## 4. Vedere quali collezioni apre la chiave

Ogni tipo di record, consegne comprese, è una [collezione](https://developers.backresto.com/it/docs/collections).
Chieda alla chiave quali raggiunge:

```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` vuoto significa che la chiave non ha ancora concessioni su collezioni.
[Richieda quelle che le servono](https://developers.backresto.com/it/docs/access).

## 5. Percorrere le consegne

Una collezione si percorre pagina per pagina con un cursore opaco. I timestamp
sono in **millisecondi dall'epoch, come stringhe**: è la convenzione dell'intera
API, mai secondi, mai 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
}
```

Le temperature sono sempre in Celsius. Qui non c'è alcun intervallo di tempo: si
percorre la collezione, si filtra su `data.timestamp` se si vuole una settimana,
e si conserva `id` per riconciliare al percorso successivo. Le altre collezioni
(temperature, raffreddamento, pulizie, etichette) si percorrono esattamente allo
stesso modo.

## 6. Recuperare le fotografie di una consegna

Le fotografie sono la collezione `delivery-pictures`. Ogni record indica la sua
consegna in `data.deliveryId`, e i byte arrivano dai suoi asset:

```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"
```

La seconda chiamata risponde con URL firmati validi per quindici minuti; scarichi
i byte senza alcun header `Authorization`. Richiede lo scope
`delivery-pictures:read`. Se la sua chiave ha solo `deliveries:read`, le
consegne rispondono e le fotografie rispondono `403`: è la concessione che fa il
suo lavoro, e la soluzione è che il cliente richieda una chiave con entrambi.

## 7. Gestire i due errori che incontrerà davvero

**`404`**: il ristorante non è sulla sua chiave, oppure il record non esiste.
I due casi sono deliberatamente indistinguibili: l'API non conferma l'esistenza
di un ristorante a un chiamante che non può vederlo.

**`403`**: il ristorante è sulla sua chiave, ma lo scope richiesto da questo
endpoint no.

Ogni errore è [un documento di problema](https://developers.backresto.com/it/docs/errors), mai una pagina HTML, e
porta un `requestId` che vale la pena citare se ci scrive.

## Dove andare adesso

- [Ottenere una chiave](https://developers.backresto.com/it/docs/access): la lista di controllo della richiesta e come modificare una chiave in seguito.
- [Autenticazione](https://developers.backresto.com/it/docs/authentication): scope, rotazione, cosa una chiave può e non può fare.
- [Paginazione](https://developers.backresto.com/it/docs/pagination): il cursore e come tenere aggiornata una copia.
- [Consegne](https://developers.backresto.com/it/docs/deliveries): ogni campo di un controllo in accettazione e delle sue fotografie.
- [Collezioni e record](https://developers.backresto.com/it/docs/collections): tutti i ventisei tipi di record e l'involucro che condividono.
- [MCP](https://developers.backresto.com/it/docs/mcp): gli stessi dati dentro un client IA, in circa tre minuti.