Guia rápido

Precisa de uma só coisa: uma chave de parceiro. Ela já sabe que restaurantes lhe foram concedidos, e a API diz-lho.

1. Obter uma chave

Escreva para contact@backresto.com com a sua empresa, os restaurantes de que precisa e os âmbitos que quer. Confirmamos com o restaurante e depois enviamos a chave ao contacto técnico que indicou. Obter uma chave é a lista de verificação completa — enviá-la completa é o que transforma a ida e volta num email em vez de quatro.

Uma chave tem este aspeto:

brp_hV8kZ2pQ.tW3nR7yL9cF1sB4xJ6mA8dK0gN5vE2uP7hQ3rT1zY6i

A metade antes do ponto é um prefixo público — identifica a chave na lista dessa página e nas conversas de suporte, e pode ser escrita sem risco. A metade a seguir é o segredo, e não aparece em mais lado nenhum além desse ecrã.

2. Guardá-la

Coloque o valor inteiro no seu gestor de segredos, como uma só cadeia de caracteres, e apague o email em que chegou. Nunca num repositório, nunca num URL, nunca numa linha de registo. Guardamos apenas um resumo criptográfico do segredo, por isso uma chave perdida significa uma revogação e uma chave nova — escreva-nos e ambas acontecem no mesmo dia.

export BACKRESTO_PARTNER_API_KEY='brp_…'

3. Encontrar o seu restaurante

Pergunte à chave que restaurantes alcança, e com que âmbitos:

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

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

A maioria das chaves alcança um só restaurante. Guarde o seu identificador para as chamadas seguintes:

export RESTAURANT_ID='restaurant-1'

4. Listar uma semana de entregas

O endpoint de listagem recebe um intervalo de tempo explícito, em milissegundos desde a época Unix, em forma de cadeia de caracteres. É a convenção em toda a API — nunca segundos, nunca 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. Obter uma entrega e as suas fotografias

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"

O endpoint das fotografias precisa do âmbito delivery-images:read além de deliveries:read. Se a sua chave só tiver o primeiro, a entrega responde e as fotografias respondem 403 — é a concessão a fazer o seu trabalho, e a solução passa por o cliente mandar emitir uma chave com ambos.

6. Ler uma das outras coleções

Tudo o que não é uma entrega — temperaturas, arrefecimento, limpeza, etiquetas — é uma coleção. Pergunte à chave quais é que ela abre:

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

Um data vazio significa que a chave ainda não tem concessões de coleções, que é o estado normal de uma chave emitida só para entregas — peça aquelas de que precisa. Caso contrário, percorra uma:

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
}

Aqui não há intervalo de tempo: percorre a coleção e guarda o id para reconciliar no percurso seguinte.

7. Lidar com as duas falhas que vai mesmo encontrar

404 — o restaurante não está na sua chave, ou a entrega não existe. Os dois casos são deliberadamente indistinguíveis: a API não confirma a um chamador que não o pode ver que um restaurante existe.

403 — o restaurante está na sua chave, mas o âmbito de que este endpoint precisa não está.

Todos os erros são um documento de problema, nunca uma página HTML, e trazem um requestId que vale a pena citar se nos escrever.

Para onde ir a seguir

• Obter uma chave — a lista de verificação do pedido, e como alterar uma chave mais tarde.
• Autenticação — âmbitos, rotação, o que uma chave pode e não pode fazer.
• Paginação — o cursor, e como percorrer um intervalo longo.
• Entregas — cada campo, e o que significa no terreno.
• Coleções e registos — os outros vinte e quatro tipos de registo, e o envelope que partilham.
• MCP — os mesmos dados dentro de um cliente de IA, em cerca de três minutos.