Guida rapida

Da una chiave a un record di consegna e a un record di collezione in cinque minuti, con curl.

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 indicando la sua azienda, i ristoranti di cui ha bisogno e gli ambiti che desidera. Confermiamo con il ristorante, poi inviamo la chiave al contatto tecnico che ha indicato. Ottenere una chiave è 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.

export BACKRESTO_PARTNER_API_KEY='brp_…'

3. Trovare il suo ristorante

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

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

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

La maggior parte delle chiavi raggiunge un solo ristorante. Tenga il suo identificativo per le chiamate seguenti:

export RESTAURANT_ID='restaurant-1'

4. Elencare una settimana di consegne

L'endpoint di elenco richiede un intervallo di tempo esplicito, in millisecondi dall'epoch, come stringhe. È la convenzione dell'intera API — mai secondi, mai ISO 8601.

curl "https://api.backresto.com/v1/restaurants/$RESTAURANT_ID/deliveries" \
  -H "Authorization: Bearer $BACKRESTO_PARTNER_API_KEY" \
  --get \
  --data-urlencode "from=1787846400000" \
  --data-urlencode "to=1788451200000" \
  --data-urlencode "limit=25"

{
  "data": [
    {
      "id": "8f2c1b04-0d5a-4b7e-9f31-6ad2c0e77a51",
      "restaurantId": "restaurant-1",
      "occurredAt": "1787932800000",
      "isCompliant": false,
      "supplier": { "id": "supplier-7", "name": "Metro Nord" },
      "temperatureRecords": [
        { "product": "Poulet fermier", "lotNumber": "L2291", "unit": "C", "value": 6.4 }
      ],
      "nonComplianceReasons": ["Température trop élevée"],
      "correctiveActions": ["Produit refusé"],
      "commentary": null,
      "imageCount": 2
    }
  ],
  "nextCursor": null
}

5. Recuperare una consegna e le sue fotografie

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

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

L'endpoint delle fotografie richiede l'ambito delivery-images:read oltre a deliveries:read. Se la sua chiave ha solo il primo, la consegna risponde e le fotografie rispondono 403 — è la concessione che fa il suo lavoro, e la soluzione è che il cliente richieda una chiave con entrambi.

6. Leggere una delle altre collezioni

Tutto ciò che non è una consegna — temperature, raffreddamento, pulizie, etichette — è una collezione. Chieda alla chiave quali apre:

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

Un data vuoto significa che la chiave non ha ancora concessioni su collezioni, che è lo stato normale di una chiave emessa per le sole consegne — richieda quelle che le servono. Altrimenti, ne percorra una:

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

{
  "data": [
    {
      "id": "3a71f0c8-9d24-4f11-bb0e-77c2e5a41d93",
      "restaurantId": "restaurant-1",
      "collection": "temperature-records",
      "deleted": false,
      "capturedAt": "1788961200000",
      "receivedAt": "1788961318000",
      "sequence": "4192",
      "data": {
        "timestamp": "1788961200000",
        "value": 3.2,
        "unit": "CELSIUS",
        "shift": "MORNING",
        "equipmentId": "equipment-12"
      }
    }
  ],
  "nextCursor": null
}

Qui non c'è alcun intervallo di tempo: si percorre la collezione e si conserva id per riconciliare al percorso successivo.

7. Gestire i due errori che incontrerà davvero

404 — il ristorante non è sulla sua chiave, oppure la consegna 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 l'ambito richiesto da questo endpoint no.

Ogni errore è un documento di problema, mai una pagina HTML, e porta un requestId che vale la pena citare se ci scrive.

Dove andare adesso

  • Ottenere una chiave — la lista di controllo della richiesta e come modificare una chiave in seguito.
  • Autenticazione — ambiti, rotazione, cosa una chiave può e non può fare.
  • Paginazione — il cursore e come percorrere un intervallo lungo.
  • Consegne — ogni campo e cosa significa sul campo.
  • Collezioni e record — gli altri ventiquattro tipi di record e l'involucro che condividono.
  • MCP — gli stessi dati dentro un client IA, in circa tre minuti.

Ultimo aggiornamento 2026-09-19.