Guida rapida

Da una chiave ai suoi primi record e a una fotografia di consegna 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 scope 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 scope:

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

export RESTAURANT_ID='restaurant-1'

4. Vedere quali collezioni apre la chiave

Ogni tipo di record, consegne comprese, è una collezione. Chieda alla chiave quali raggiunge:

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 vuoto significa che la chiave non ha ancora concessioni su collezioni. Richieda quelle che le servono.

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.

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
}

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:

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, 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: scope, rotazione, cosa una chiave può e non può fare.
  • Paginazione: il cursore e come tenere aggiornata una copia.
  • Consegne: ogni campo di un controllo in accettazione e delle sue fotografie.
  • Collezioni e record: tutti i ventisei tipi di record e l'involucro che condividono.
  • MCP: gli stessi dati dentro un client IA, in circa tre minuti.

Ultimo aggiornamento 2026-09-29.