Ressourcen

Dokumente

Jeder Dokumente-Endpunkt, mit dem Scope, den er durchsetzt, dem Körper, den er annimmt, einer lesbaren Antwort und den Ablehnungen, die er zurückgeben kann.

Alle Dokumente in der Dokumentenbibliothek des Arbeitsbereichs auflisten.

get/organizations/{organization}/documents

Scope: documents:read
Idempotency-Key: Wird nicht akzeptiert
Liefert: 200

Pfadparameter

organizationZeichenkettePflicht

Die Organisation, für die diese Anfrage handelt. Der Zugangsschlüssel muss dafür freigegeben sein.

Abfrageparameter

limitZeichenketteOptional

Wie viele Datensätze zurückgegeben werden. Der Server darf weniger liefern.

cursorZeichenketteOptional

Der next_cursor der vorherigen Seite. Ein Cursor kodiert die Filter, unter denen er ausgegeben wurde; wird er mit anderen Filtern gesendet, folgt eine Ablehnung mit cursor_invalid.

typeZeichenketteOptional

Nur Dokumente dieses Typs zurückgeben.

access_tierZeichenketteOptional

Nur Dokumente zurückgeben, die für diese Lesergruppe veröffentlicht sind.

Fehler

Jede Ablehnung, die dieser Endpunkt zurückgeben kann, samt dem HTTP-Status, mit dem sie eintrifft.

Anfrage

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/documents?type=conformity_declaration" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Antwort · 200

{
  "object": "list",
  "data": [
    {
      "object": "document",
      "id": "a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b",
      "type": "conformity_declaration",
      "access_tier": "public",
      "file_name": "doc-2026-kestrel.pdf",
      "display_name": "EU Declaration of Conformity",
      "mime_type": "application/pdf",
      "file_size": 184320,
      "upload_state": "ready",
      "uploaded_at": "2026-07-29T15:44:02.008Z",
      "livemode": true,
      "created_at": "2026-07-29T15:43:51.660Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/documents?type=conformity_declaration

Dokumente eines Produktpasses auflisten.

get/organizations/{organization}/passports/{id}/documents

Scope: documents:read
Idempotency-Key: Wird nicht akzeptiert
Liefert: 200

Pfadparameter

organizationZeichenkettePflicht

Die Organisation, für die diese Anfrage handelt. Der Zugangsschlüssel muss dafür freigegeben sein.

idZeichenkettePflicht

Die Kennung der Ressource. Behandeln Sie sie als undurchsichtige Zeichenkette.

Abfrageparameter

limitZeichenketteOptional

Wie viele Datensätze zurückgegeben werden. Der Server darf weniger liefern.

cursorZeichenketteOptional

Der next_cursor der vorherigen Seite. Ein Cursor kodiert die Filter, unter denen er ausgegeben wurde; wird er mit anderen Filtern gesendet, folgt eine Ablehnung mit cursor_invalid.

typeZeichenketteOptional

Nur Dokumente dieses Typs zurückgeben.

access_tierZeichenketteOptional

Nur Dokumente zurückgeben, die für diese Lesergruppe veröffentlicht sind.

Fehler

Jede Ablehnung, die dieser Endpunkt zurückgeben kann, samt dem HTTP-Status, mit dem sie eintrifft.

Anfrage

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents?access_tier=public" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Antwort · 200

{
  "object": "list",
  "data": [
    {
      "object": "document",
      "id": "a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents/a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "type": "conformity_declaration",
      "access_tier": "public",
      "file_name": "doc-2026-kestrel.pdf",
      "display_name": "EU Declaration of Conformity",
      "mime_type": "application/pdf",
      "file_size": 184320,
      "upload_state": "ready",
      "uploaded_at": "2026-07-29T15:44:02.008Z",
      "livemode": true,
      "created_at": "2026-07-29T15:43:51.660Z",
      "linked_at": "2026-07-29T15:43:51.660Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents?access_tier=public

Ein Dokument anlegen und eine signierte Upload-URL erhalten.

post/organizations/{organization}/passports/{id}/documents

Scope: documents:write
Idempotency-Key: Wird akzeptiert
Liefert: 201

Pfadparameter

organizationZeichenkettePflicht

Die Organisation, für die diese Anfrage handelt. Der Zugangsschlüssel muss dafür freigegeben sein.

idZeichenkettePflicht

Die Kennung der Ressource. Behandeln Sie sie als undurchsichtige Zeichenkette.

Anfragekörper

Dieser Endpunkt akzeptiert einen von zwei Anfragekörpern. Senden Sie genau eine Variante — ein Anfragekörper mit Feldern aus beiden wird abgelehnt.

Ein bereits in der Bibliothek vorhandenes Dokument verknüpfen

document_idZeichenkettePflicht

Ein bereits in der Dokumentenbibliothek der Organisation vorhandenes Dokument verknüpfen, statt eines hochzuladen. Nicht mit den Upload-Feldern kombinierbar. Wird ein noch nicht angehängtes Dokument verknüpft, antwortet die API mit 201; wird ein bereits angehängtes erneut verknüpft, mit 200. Beide Antworten führen kein upload-Objekt mit.

Eine neue Datei hochladen

typeZeichenkettePflicht

Beim Hochladen erforderlich; muss fehlen, wenn document_id gesetzt ist. Einer der Werte certification, image, document, conformity_declaration. Ein image mit access_tier: public wird als Produktfoto auf der veröffentlichten Produktpass-Seite angezeigt; mehrere ergeben eine Galerie. Diese API kann nicht bestimmen, welches davon das Hauptbild ist — das legt eine Person im Produktpass-Editor unter den Produktfotos fest. Kein Kategorieschema enthält ein Bildfeld; das Hochladen ist der einzige Weg zu einem Produktfoto.

access_tierZeichenkettePflicht

Beim Hochladen erforderlich; muss fehlen, wenn document_id gesetzt ist. Einer der Werte public, restricted, authority. Er entscheidet, wer die Datei lesen darf, sobald der Produktpass live ist.

file_nameZeichenkettePflicht

Beim Hochladen erforderlich; muss fehlen, wenn document_id gesetzt ist. Der Dateiname, unter dem gespeichert wird.

mime_typeZeichenkettePflicht

Beim Hochladen erforderlich; muss fehlen, wenn document_id gesetzt ist. Einer der Werte application/pdf, image/png, image/jpeg, image/webp. Der Wert wird unverändert an den Speicher weitergereicht, der eine Abweichung ablehnt.

file_sizeGanzzahlOptional

Größe in Bytes, bis zu 10485760.

display_nameZeichenketteOptional

Die Bezeichnung, die ein Leser zu sehen bekommt. Voreingestellt ist file_name.

Fehler

Jede Ablehnung, die dieser Endpunkt zurückgeben kann, samt dem HTTP-Status, mit dem sie eintrifft.

Anfrage

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "conformity_declaration",
  "access_tier": "public",
  "file_name": "doc-2026-kestrel.pdf",
  "mime_type": "application/pdf",
  "file_size": 184320,
  "display_name": "EU Declaration of Conformity"
}'

Antwort · 201

{
  "object": "document",
  "id": "a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents/a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "type": "conformity_declaration",
  "access_tier": "public",
  "file_name": "doc-2026-kestrel.pdf",
  "display_name": "EU Declaration of Conformity",
  "mime_type": "application/pdf",
  "file_size": 184320,
  "upload_state": "pending",
  "uploaded_at": null,
  "livemode": true,
  "created_at": "2026-08-02T09:40:12.331Z",
  "linked_at": "2026-08-02T09:40:12.331Z",
  "upload": {
    "url": "https://<project>.supabase.co/storage/v1/object/upload/sign/passport-assets/<organization>/library/<uuid>-doc-2026-kestrel.pdf?token=<jwt>",
    "method": "PUT",
    "headers": {
      "Content-Type": "application/pdf"
    },
    "expires_at": "2026-08-02T11:40:12.331Z",
    "max_bytes": 10485760
  }
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents