# Guía rápida

> De una clave a sus primeros registros y a una fotografía de entrega en cinco minutos, con curl.

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

Necesita una sola cosa: una clave de partner. Ya sabe qué restaurantes se le
concedieron, y la API se lo dice.

## 1. Obtenga una clave

Escriba a [contact@backresto.com](mailto:contact@backresto.com?subject=Partner%20API%20key%20request)
indicando su empresa, los restaurantes que necesita y los scopes que quiere. Lo
confirmamos con el restaurante y después enviamos la clave al contacto técnico
que haya indicado. [Obtener una clave](https://developers.backresto.com/es/docs/access) es la lista de comprobación
completa: enviarla completa es lo que hace que la ida y vuelta sea un correo en
lugar de cuatro.

Una clave tiene este aspecto:

```
brp_hV8kZ2pQ.tW3nR7yL9cF1sB4xJ6mA8dK0gN5vE2uP7hQ3rT1zY6i
```

La mitad anterior al punto es un prefijo público: identifica la clave en la lista
de esa página y en las conversaciones con soporte, y se puede anotar sin riesgo.
La mitad posterior es el secreto, y no aparece en ningún sitio salvo en esa única
pantalla.

## 2. Guárdela

Ponga el valor completo en su gestor de secretos, como una sola cadena, y borre el
correo en el que llegó. Nunca un repositorio, nunca una URL, nunca una línea de
log. Solo conservamos un resumen criptográfico del secreto, así que una clave
perdida significa una revocación y una nueva: escríbanos y ambas cosas ocurren el
mismo día.

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

## 3. Encuentre su restaurante

Pregunte a la clave qué restaurantes alcanza, y con qué 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"]
    }
  ]
}
```

La mayoría de las claves alcanzan un solo restaurante. Guarde su identificador
para las llamadas siguientes:

```bash
export RESTAURANT_ID='restaurant-1'
```

## 4. Vea qué colecciones abre la clave

Todo tipo de registro, las entregas incluidas, es una [colección](https://developers.backresto.com/es/docs/collections).
Pregunte a la clave cuáles alcanza:

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

Un `data` vacío significa que la clave todavía no tiene ninguna concesión de
colección. [Pida las que necesite](https://developers.backresto.com/es/docs/access).

## 5. Recorra las entregas

Una colección se recorre página a página con un cursor opaco. Las marcas de
tiempo son **milisegundos desde la época Unix, como cadenas**: esa es la
convención en toda la 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
}
```

Las temperaturas están siempre en Celsius. Aquí no hay rango de tiempo: usted
recorre la colección, filtra por `data.timestamp` si quiere una semana, y guarda
el `id` para conciliar en el siguiente recorrido. Las demás colecciones
(temperaturas, enfriamiento, limpieza, etiquetas) se recorren exactamente igual.

## 6. Obtenga las fotografías de una entrega

Las fotografías son la colección `delivery-pictures`. Cada registro nombra su
entrega en `data.deliveryId`, y los bytes salen de sus archivos adjuntos:

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

La segunda llamada responde con URL firmadas válidas durante quince minutos;
descargue los bytes sin cabecera `Authorization`. Necesita el scope
`delivery-pictures:read`. Si su clave solo tiene `deliveries:read`, las entregas
responden y las fotografías responden `403`: es la concesión cumpliendo su
cometido, y la solución es que el cliente pida una clave con los dos.

## 7. Gestione los dos fallos con los que realmente se topará

**`404`**: el restaurante no está en su clave, o el registro no existe. Ambos
casos son deliberadamente indistinguibles: la API no confirma la existencia de
un restaurante a quien no puede verlo.

**`403`**: el restaurante sí está en su clave, pero el scope que este endpoint
necesita no lo está.

Todo error es [un documento de problema](https://developers.backresto.com/es/docs/errors), nunca una página HTML, y
lleva un `requestId` que conviene citar si nos escribe.

## Dónde seguir

- [Obtener una clave](https://developers.backresto.com/es/docs/access): la lista de comprobación de la solicitud, y cómo cambiar una clave más adelante.
- [Autenticación](https://developers.backresto.com/es/docs/authentication): scopes, rotación, qué puede y qué no puede hacer una clave.
- [Paginación](https://developers.backresto.com/es/docs/pagination): el cursor, y cómo mantener una copia al día.
- [Entregas](https://developers.backresto.com/es/docs/deliveries): cada campo de un control de recepción y sus fotografías.
- [Colecciones y registros](https://developers.backresto.com/es/docs/collections): los veintiséis tipos de registro, y el sobre que comparten.
- [MCP](https://developers.backresto.com/es/docs/mcp): los mismos datos dentro de un cliente de IA, en unos tres minutos.