Dokumente

Jedes Restaurant hält neben den Kontrollen auch Papier: Bescheinigungen von Lieferanten, Reinigungsverfahren, den letzten Kontrollbericht, einen unterschriebenen Plan. Die App gibt ihm einen Ort, es abzulegen, und diese Collection ist dieser Aktenschrank — ein Datensatz pro Dokument, jeder auf die Datei selbst zeigend.

Sie teilt sich den Snapshot-Umschlag: id, deleted, capturedAt, receivedAt, sequence und der Rest stehen um das data darunter herum.

drive-files

{
  "id": "a94c7e51-3f60-4b2d-8e17-05c9d3a6f482",
  "collection": "drive-files",
  "deleted": false,
  "capturedAt": "1789743015220",
  "receivedAt": "1789743098644",
  "sequence": "97",
  "data": {
    "s3Key": "drive/fournisseurs/attestation-metro-2026.pdf",
    "name": "Attestation Metro 2026.pdf",
    "sizeBytes": 184320,
    "contentType": "application/pdf",
    "asset": {
      "objectKey": "restaurants/36eaa3fa/drive/a17c93be4f02",
      "status": "uploaded",
      "contentType": "application/pdf",
      "byteLength": 184320,
      "sha256": "9f2a7c41e8b0d5364a1f8e29b7c30d5e6f14a8b29c7d0e3f5a6b1c8d9e0f2a3b"
    }
  }
}

In data gibt es kein timestamp. Wann das Dokument abgelegt wurde, steht wie bei jeder anderen Collection in capturedAt auf dem Umschlag.

Die Datei ist der Punkt

Anderswo ist der Datensatz die Information und die Datei der Beleg. Hier ist es umgekehrt: Fünf Felder beschreiben ein Dokument, dessen Inhalt der ganze Grund ist, aus dem jemand diese Collection liest. Sie werden also fast immer dem Datensatz bis zu den Bytes folgen.

GET /v1/restaurants/{restaurantId}/collections/drive-files/records/{recordId}/assets

Signierte URLs, fünfzehn Minuten gültig, jede mit ihrer eigenen Autorisierung. Die Collections-Seite hat die Regeln, und zwei davon zählen hier mehr als sonst irgendwo:

• sha256 erspart Ihnen einen Download. Es ist die Prüfsumme der Bytes. Eine Bescheinigung, die sich seit Ihrem letzten Durchlauf nicht geändert hat, muss nicht erneut geholt werden, und Dokumente sind das Größte, was diese API Ihnen reicht.
• Jetzt abrufen, die Bytes speichern, nie den Link. Fünfzehn Minuten reichen zum Herunterladen und sind kurz genug, dass eine URL in Ihrer Datenbank bis zum Morgen ein toter Link ist.

asset beschreibt die Datei; herausgeben tut sie nur der Endpunkt. Es trägt objectKey, status, contentType, byteLength und sha256 — genug, um zu entscheiden, ob Sie die Bytes wollen, und keine URL, denn eine URL, die nie abläuft, wäre ein dauerhafter unauthentifizierter Link zu den Unterlagen eines Restaurants.

status ist das Feld, auf das Sie verzweigen. Es ist uploaded, sobald die Bytes angekommen und geprüft sind, und pending, solange ein Gerät sie noch sendet. Ein Asset mit pending fehlt beim Assets-Endpunkt, und das ist richtig so, statt kaputt zu sein: Fragen Sie später erneut, statt es als fehlendes Dokument zu behandeln. asset ist außerdem das eine Feld hier, das ganz fehlen kann — ein Datensatz, der noch ohne Datei abgelegt wurde.

Das sind keine Bilder

Ein Reinigungsbeleg ist ein Foto. Ein Dokument ist, was immer das Restaurant abgelegt hat: eine PDF-Bescheinigung, ein Temperaturexport als Excel oder CSV, ein Verfahren in Word, ein Scan, den jemand mit dem Telefon gemacht hat. All das taucht hier auf.

Lesen Sie contentType, statt einen anzunehmen. Im Datensatz darf es null sein — die App hat ihn nicht immer —, nehmen Sie also, wenn es null ist, stattdessen den contentType vom Asset; der ist der Medientyp des Objekts, das tatsächlich gespeichert ist, und ihm ist zu trauen, wenn die beiden sich widersprechen. Ein Client, der alles als Bild darstellt oder alles als .pdf speichert, geht bei der ersten Tabelle kaputt.

Leiten Sie den Typ auch nicht aus name oder s3Key ab. Eine Endung ist eine Konvention, keine Garantie, und beide Felder sind Freitext von einer Person, die auf einem Tablet eine Datei benennt.

Sie auf Ihrer Seite ablegen

s3Key ist ein Schlüssel, keine Adresse. Er benennt das Objekt im Speicher — er hat kein Schema, keinen Host und keinen führenden Schrägstrich, und Sie können ihn nicht abrufen. Jedes Byte, das Sie bekommen, kommt vom Assets-Endpunkt.

Schlüsseln Sie auf das id des Umschlags, nicht auf name. Nichts hindert zwei Dokumente daran, Attestation 2026.pdf zu heißen, im selben Restaurant, ein Jahr auseinander abgelegt.

Es lohnt sich, sizeBytes vor dem Download zu lesen. Es ist der billigste Weg zu entscheiden, ob Sie einen 40 MB großen Scan über eine Mobilverbindung ziehen. Maßgeblich ist das byteLength des gespeicherten Objekts selbst, auf dem Asset.

Eine Löschmarkierung nimmt die Datei mit. deleted: true heißt, dass das Dokument in der App entfernt wurde, und seine Assets werden nicht mehr aufgelistet — wenn Sie diese Bescheinigung gebraucht haben, haben Sie die Bytes gebraucht. Wie sich Löschmarkierungen verhalten, steht auf der Seite zum Umschlag.