# Schnellstart

> Von einem Schlüssel zu Ihren ersten Datensätzen und einem Lieferfoto in fünf Minuten, mit curl.

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

Sie brauchen nur eines: einen Partnerschlüssel. Er weiß bereits, welche
Restaurants ihm freigegeben wurden, und die API sagt es Ihnen.

## 1. Einen Schlüssel besorgen

Schreiben Sie an [contact@backresto.com](mailto:contact@backresto.com?subject=Partner%20API%20key%20request)
mit Ihrem Unternehmen, den Restaurants, die Sie brauchen, und den Scopes, die
Sie wollen. Wir stimmen uns mit dem Restaurant ab und senden
den Schlüssel dann an den technischen Kontakt, den Sie genannt haben.
[Einen Schlüssel erhalten](https://developers.backresto.com/de/docs/access) ist die vollständige Checkliste, und
wer sie vollständig sendet, macht aus dem Hin und Her eine E-Mail statt vier.

Ein Schlüssel sieht so aus:

```
brp_hV8kZ2pQ.tW3nR7yL9cF1sB4xJ6mA8dK0gN5vE2uP7hQ3rT1zY6i
```

Die Hälfte vor dem Punkt ist ein öffentliches Präfix: Es benennt den Schlüssel
in der Liste auf jener Seite und in Support-Gesprächen, und man darf es
aufschreiben. Die Hälfte dahinter ist das Secret, und es erscheint nirgends
außer auf diesem einen Bildschirm.

## 2. Ihn speichern

Legen Sie den gesamten Wert als einen einzigen String in Ihren Secret Manager
und löschen Sie die E-Mail, mit der er kam. Nie ein Repository, nie eine
URL, nie eine Logzeile. Wir behalten nur einen Digest des Secrets, ein
verlorener Schlüssel bedeutet also einen Widerruf und einen neuen. Schreiben
Sie uns, und beides passiert am selben Tag.

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

## 3. Ihr Restaurant finden

Fragen Sie den Schlüssel, welche Restaurants er erreicht und mit welchen 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"]
    }
  ]
}
```

Die meisten Schlüssel erreichen ein Restaurant. Behalten Sie seine Kennung für die folgenden Aufrufe:

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

## 4. Sehen, welche Collections der Schlüssel öffnet

Jeder Datensatztyp, Lieferungen eingeschlossen, ist eine [Collection](https://developers.backresto.com/de/docs/collections).
Fragen Sie den Schlüssel, welche er erreicht:

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

Ein leeres `data` heißt, dass der Schlüssel noch keine Collection-Zuweisungen
hat. [Fragen Sie nach denen, die Sie brauchen](https://developers.backresto.com/de/docs/access).

## 5. Die Lieferungen durchlaufen

Eine Collection wird Seite für Seite mit einem undurchsichtigen Cursor
durchlaufen. Zeitstempel sind **Millisekunden seit Epoch, als Strings**: Das ist
die Konvention in der gesamten API, nie Sekunden, nie 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
}
```

Temperaturen sind immer in Celsius. Hier kein Zeitraum: Sie durchlaufen die
Collection, filtern nach `data.timestamp`, wenn Sie eine Woche wollen, und
behalten `id`, um beim nächsten Durchlauf abzugleichen. Die anderen Collections
(Temperaturen, Kühlen, Reinigung, Etiketten) werden genauso durchlaufen.

## 6. Die Fotos einer Lieferung abrufen

Fotos sind die Collection `delivery-pictures`. Jeder Datensatz nennt seine
Lieferung in `data.deliveryId`, und die Bytes kommen von seinen Assets:

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

Der zweite Aufruf antwortet mit signierten URLs, die fünfzehn Minuten gültig
sind; laden Sie die Bytes ohne `Authorization`-Header herunter. Er braucht den
Scope `delivery-pictures:read`. Hat Ihr Schlüssel nur `deliveries:read`,
antworten die Lieferungen und die Fotos antworten `403`: Das ist die Zuweisung,
die ihre Arbeit tut, und die Lösung ist, dass der Kunde einen Schlüssel mit
beiden ausstellen lässt.

## 7. Die beiden Fehler behandeln, die Ihnen wirklich begegnen

**`404`**: Das Restaurant steht nicht auf Ihrem Schlüssel, oder der Datensatz
existiert nicht. Beides ist bewusst nicht unterscheidbar: Die API bestätigt
einem Aufrufer, der es nicht sehen kann, nicht, dass ein Restaurant existiert.

**`403`**: Das Restaurant steht auf Ihrem Schlüssel, aber der Scope, den
dieser Endpunkt braucht, nicht.

Jeder Fehler ist [ein Problemdokument](https://developers.backresto.com/de/docs/errors), nie eine HTML-Seite, und
trägt eine `requestId`, die zu nennen sich lohnt, wenn Sie uns schreiben.

## Wie es weitergeht

- [Einen Schlüssel erhalten](https://developers.backresto.com/de/docs/access): die Checkliste für die Anfrage und wie Sie einen Schlüssel später ändern.
- [Authentifizierung](https://developers.backresto.com/de/docs/authentication): Scopes, Schlüsselwechsel, was ein Schlüssel kann und was nicht.
- [Paginierung](https://developers.backresto.com/de/docs/pagination): der Cursor und wie Sie eine Kopie aktuell halten.
- [Lieferungen](https://developers.backresto.com/de/docs/deliveries): jedes Feld einer Wareneingangskontrolle und ihrer Fotos.
- [Collections & Datensätze](https://developers.backresto.com/de/docs/collections): alle sechsundzwanzig Datensatztypen und der Umschlag, den sie teilen.
- [MCP](https://developers.backresto.com/de/docs/mcp): dieselben Daten in einem KI-Client, in etwa drei Minuten.