# Support & Datenvollständigkeit

> Was die aktuellen Daten abdecken und was nicht, wie die API versioniert wird und wie Sie einen Menschen erreichen.

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

## Der Vorbehalt zur Vollständigkeit, klar gesagt

Die Partner-API stellt Datensätze bereit, die erfasst wurden, **nachdem die
Funktion für dieses Restaurant freigeschaltet wurde**, in jeder
[Collection](https://developers.backresto.com/de/docs/collections). Sie beansprucht nicht, die vollständige
Historie eines Restaurants zu halten, und sie wird auch keine nachtragen.
Lieferungen sind die einzige Ausnahme: Ihre beiden Collections tragen die
Historie, die die App noch hielt, als sie geöffnet wurden.

Das wiegt schwerer, als es klingt:

- Ein leeres Ergebnis ist **kein** Beleg dafür, dass nichts passiert ist. Es
  kann heißen, dass das Restaurant noch nicht freigeschaltet war oder dass ein
  Gerät noch nicht hochgeladen hat.
- Eine Anzahl aus dieser API ist keine Compliance-Kennzahl. Drucken Sie keine
  auf einen Bericht, der sich wie ein Audit liest.
- Wenn Sie das Freischaltdatum eines Restaurants wissen müssen, fragen Sie uns
  oder den Kunden. Es wird derzeit nicht über die API bereitgestellt. Wenn Sie
  es als Feld brauchen, sagen Sie es uns, und es wird eines.

Collections sagen das in ihrer eigenen Antwort: `stateKind` ist
`received-shadow-snapshot`, also der Zustand, den diese API empfangen hat, und
nicht der Zustand, den die App des Restaurants hält. Beide stimmen im Normalfall
überein und laufen genau dann auseinander, wenn ein Gerät noch nicht
hochgeladen hat.

Sobald ein Restaurant freigeschaltet ist, treffen die Datensätze zuverlässig
ein, auch die, die erfasst wurden, während ein Gerät offline war: Sie werden
hochgeladen, wenn es sich wieder verbindet, und deshalb sollten sich
[inkrementelle Abfragen überlappen](https://developers.backresto.com/de/docs/pagination) und deshalb trägt jeder
Datensatz sowohl `capturedAt` als auch `receivedAt`.

## Versionierung

Jeder Pfad trägt das Präfix `/v1`, und **diese API ist in geschlossener Beta.**
Schlüssel werden von Hand vergeben, an eine Handvoll Integratoren, und die Form
der API steht noch nicht fest. Nehmen Sie das wörtlich: Innerhalb von `/v1`
kann ein Endpunkt, solange die Beta läuft, seine Form ändern oder zurückgezogen
werden, und wir versprechen nichts anderes.

Was das in der Praxis heißt:

- **Parsen Sie nachsichtig.** Ignorieren Sie Felder, die Sie nicht kennen, statt
  an ihnen zu scheitern; es kommen häufig welche dazu.
- **Achten Sie auf zurückgezogene Endpunkte.** Die eigenen Lieferungs-Endpunkte
  und der Scope, der ihre Fotos geöffnet hat, sind weg: Lieferungen werden als
  [Collections](https://developers.backresto.com/de/docs/collections) gelesen, wie jeder andere Datensatztyp. Siehe
  unten.
- **Sagen Sie uns, dass es Sie gibt.** Wir wissen, welche Schlüssel uns
  aufgerufen haben und wann. Ist Ihrer in Gebrauch, melden wir uns, bevor wir
  etwas darunter verschieben, nicht weil die Beta uns dazu verpflichtet,
  sondern weil eine funktionierende Integration überraschend zu zerbrechen eine
  schlechte Art ist, eine zu führen.

Wenn die Beta endet, wird dieser Abschnitt zum gewohnten Versprechen: additive
Änderungen innerhalb einer Version, alles andere hinter `/v2`. So weit ist es
noch nicht, und das zu sagen nützt Ihnen mehr als eine Garantie, die wir
zurücknehmen müssten.

Das [OpenAPI-Dokument](https://api.backresto.com/openapi.json) wird aus dem
laufenden Dienst erzeugt und ist damit die maßgebliche Beschreibung dessen, was
gerade ausgerollt ist. Wenn diese Dokumentation und jenes Dokument voneinander
abweichen, hat das Dokument recht und wir haben eine Seite zu korrigieren.
Bitte sagen Sie es uns.

## Health-Checks

Zwei öffentliche Endpunkte, ohne Authentifizierung:

| Endpunkt | Bedeutung |
| --- | --- |
| `GET /health/live` | Der Prozess läuft. |
| `GET /health/ready` | Der Prozess erreicht seine Datenbank und kann Anfragen bedienen. |

`/health/ready` ist der, den Sie abfragen sollten, wenn Sie uns überwachen.
Erfolgreiche Prüfungen werden nicht ins Audit-Log geschrieben, ein Monitor
erzeugt also kein Rauschen.

## Hilfe bekommen

Schreiben Sie an [contact@backresto.com](mailto:contact@backresto.com). Was eine
Antwort schnell macht:

- die `requestId` aus dem Problemdokument oder die `X-Request-ID`, die Sie
  gesendet haben;
- das **öffentliche Präfix** Ihres Schlüssels (die `brp_…`-Hälfte vor dem
  Punkt, niemals das Secret);
- die Umgebung, den Endpunkt und ungefähr wann.

Senden Sie uns niemals das Secret eines Schlüssels: Das öffentliche Präfix
benennt ihn eindeutig. Ist ein Secret irgendwohin geraten, wo es nicht
hingehört, schreiben Sie das in die Betreffzeile und senden Sie das Präfix: Der
Widerruf wirkt sofort, und er ist die ganze Abhilfe. Der Rest des
Schlüssel-Lebenszyklus steht unter [Einen Schlüssel erhalten](https://developers.backresto.com/de/docs/access).

## Mehr verlangen

Was es hier gibt, gibt es, weil jemand danach gefragt hat. Gar- und
Kühltemperaturen, Reinigungspläne, Etiketten und ein gehosteter MCP-Endpunkt
standen vor ein paar Monaten alle auf dieser Liste; sie sind heute
[Collections](https://developers.backresto.com/de/docs/collections) und [ein Endpunkt](https://developers.backresto.com/de/docs/mcp).

**Lieferungen waren der letzte Punkt auf dieser Liste.** Sie waren das Erste,
was diese API ausgeliefert hat, über eigene Endpunkte, mit eigener Struktur und
einem Zeitraum statt eines Cursors. Heute sind sie zwei Collections,
`deliveries` und `delivery-pictures`, gelesen über denselben Umschlag, dieselbe
Paginierung und dasselbe `GET .../collections/{collection}/records` wie jeder
andere Datensatztyp, und die alten Endpunkte sind zurückgezogen, statt daneben
bestehen zu bleiben. Ein einziger Weg, einen Datensatz zu lesen, ist der Sinn
der Änderung. Wenn Sie gegen die alten Endpunkte gebaut haben, zeigt
[Lieferungen](https://developers.backresto.com/de/docs/deliveries) die neue Struktur, und wir helfen Ihnen gern
beim Umstieg.

Was noch darauf steht: Webhooks statt Abfragen, ein inkrementeller Cursor auf
Collections, ein Freischaltdatum am Restaurant und eine OAuth-Anmeldung für die
MCP-Clients, die keinen Schlüssel nehmen. Welches als Nächstes kommt,
entscheidet, wer fragt. Also fragen Sie.