Guia rápido

De uma chave aos seus primeiros registos e a uma fotografia de entrega em cinco minutos, com curl.

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 scopes 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 scopes:

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"]
    }
  ]
}

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

export RESTAURANT_ID='restaurant-1'

4. Ver que coleções a chave abre

Todos os tipos de registo, incluindo as entregas, são uma coleção. Pergunte à chave quais é que ela alcança:

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
    }
  ]
}

Um data vazio significa que a chave ainda não tem concessões de coleções. Peça aquelas de que precisa.

5. Percorrer as entregas

Uma coleção percorre-se página a página com um cursor opaco. As marcas temporais estão 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/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
}

As temperaturas estão sempre em graus Celsius. Aqui não há intervalo de tempo: percorre a coleção, filtra por data.timestamp se quiser uma semana, e guarda o id para reconciliar no percurso seguinte. As outras coleções (temperaturas, arrefecimento, limpeza, etiquetas) percorrem-se exatamente da mesma maneira.

6. Obter as fotografias de uma entrega

As fotografias são a coleção delivery-pictures. Cada registo indica a sua entrega em data.deliveryId, e os bytes vêm dos seus ficheiros:

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"

A segunda chamada responde com URL assinados válidos durante quinze minutos; transfira os bytes sem qualquer cabeçalho Authorization. Precisa do scope delivery-pictures:read. Se a sua chave só tiver deliveries:read, as entregas respondem 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.

7. Lidar com as duas falhas que vai mesmo encontrar

404: o restaurante não está na sua chave, ou o registo não existe. Os dois casos são deliberadamente indistinguíveis: a API não confirma a existência de um restaurante a quem não o pode ver.

403: o restaurante está na sua chave, mas o scope 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: scopes, rotação, o que uma chave pode e não pode fazer.
  • Paginação: o cursor, e como manter uma cópia atualizada.
  • Entregas: cada campo de um controlo de receção e as suas fotografias.
  • Coleções e registos: os vinte e seis tipos de registo, e o envelope que partilham.
  • MCP: os mesmos dados dentro de um cliente de IA, em cerca de três minutos.

Última atualização em 2026-09-29.