# Guia rápido

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

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

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](mailto:contact@backresto.com?subject=Partner%20API%20key%20request)
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](https://developers.backresto.com/pt/docs/access) é 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.

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

## 3. Encontrar o seu restaurante

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

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

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

```bash
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](https://developers.backresto.com/pt/docs/collections). Pergunte à chave quais é que ela alcança:

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

Um `data` vazio significa que a chave ainda não tem concessões de coleções.
[Peça aquelas de que precisa](https://developers.backresto.com/pt/docs/access).

## 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.

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

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:

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

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](https://developers.backresto.com/pt/docs/errors), 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](https://developers.backresto.com/pt/docs/access): a lista de verificação do pedido, e como alterar uma chave mais tarde.
- [Autenticação](https://developers.backresto.com/pt/docs/authentication): scopes, rotação, o que uma chave pode e não pode fazer.
- [Paginação](https://developers.backresto.com/pt/docs/pagination): o cursor, e como manter uma cópia atualizada.
- [Entregas](https://developers.backresto.com/pt/docs/deliveries): cada campo de um controlo de receção e as suas fotografias.
- [Coleções e registos](https://developers.backresto.com/pt/docs/collections): os vinte e seis tipos de registo, e o envelope que partilham.
- [MCP](https://developers.backresto.com/pt/docs/mcp): os mesmos dados dentro de um cliente de IA, em cerca de três minutos.