Produktpässe — API-Referenz von PassportCraft

Produktpässe auflisten.

get/organizations/{organization}/passports

Scope: passports: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.

statusZeichenketteOptional

Nur Produktpässe in diesem Status zurückgeben.

categoryZeichenketteOptional

Nur Produktpässe in dieser Kategorie zurückgeben.

updated_sinceZeichenketteOptional

Ein RFC 3339-Zeitstempel. Zurückgegeben werden Produktpässe, die zu diesem Zeitpunkt oder danach geändert wurden — so fragt eine Integration Änderungen ab, ohne den gesamten Katalog erneut zu lesen.

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?status=published&limit=25" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Antwort · 200

{
  "object": "list",
  "data": [
    {
      "object": "passport",
      "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "category": "textile",
      "status": "published",
      "gtin": "02000000000053",
      "external_id": "SKU-4471-BLK",
      "version": 4,
      "livemode": true,
      "created_at": "2026-08-01T09:12:44.918Z",
      "updated_at": "2026-08-01T14:03:22.501Z",
      "data": {
        "product_name": "Merino Crew Neck",
        "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
        "manufacturer_name": "Atelier Kestrel SAS",
        "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
        "manufacturer_country": "FR",
        "material_composition": [
          {
            "fiber": "Merino wool",
            "percentage": 100
          }
        ],
        "substances_of_concern": [
          "None above threshold"
        ],
        "gtin": "02000000000053"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports?status=published&limit=25

Einen Produktpass erstellen.

post/organizations/{organization}/passports

Scope: passports: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.

Anfragekörper

categoryZeichenkettePflicht

Eine Kategoriekennung aus GET /categories. Sie legt das Feldschema fest und lässt sich nachträglich nicht mehr ändern.

external_idZeichenketteOptional

Ihre eigene Kennung für dieses Produkt, 1 bis 255 Zeichen. Innerhalb der Organisation und des Modus eindeutig — genau das erlaubt Ihnen den Abgleich, ohne unsere Kennungen zu speichern; dieselbe Kennung kann also einmal im Test- und einmal im Live-Modus vorkommen.

dataObjektOptional

Der Inhalt des Produktpasses. Die Schlüssel sind Feldnamen aus dem Kategorieschema sowie der Begleitschlüssel document_id_key jedes dokumentfähigen Feldes; alles andere wird abgelehnt statt stillschweigend gespeichert.

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" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "category": "textile",
  "external_id": "SKU-4471-BLK",
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR"
  }
}'

Antwort · 201

{
  "object": "passport",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "category": "textile",
  "status": "draft",
  "gtin": null,
  "serial_number": null,
  "external_id": "SKU-4471-BLK",
  "version": 1,
  "livemode": true,
  "registry_id": null,
  "created_at": "2026-08-01T09:12:44.918Z",
  "updated_at": "2026-08-01T09:12:44.918Z",
  "published_at": null,
  "trashed_at": null,
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR",
    "material_composition": [
      {
        "fiber": "Merino wool",
        "percentage": 100
      }
    ],
    "substances_of_concern": [
      "None above threshold"
    ]
  }
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports

Einen Produktpass abrufen.

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

Scope: passports: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.

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" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Antwort · 200

{
  "object": "passport",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "category": "textile",
  "status": "published",
  "gtin": "02000000000053",
  "serial_number": null,
  "external_id": "SKU-4471-BLK",
  "version": 4,
  "livemode": true,
  "registry_id": null,
  "created_at": "2026-08-01T09:12:44.918Z",
  "updated_at": "2026-08-01T14:03:22.501Z",
  "published_at": "2026-08-01T14:03:22.501Z",
  "trashed_at": null,
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR",
    "material_composition": [
      {
        "fiber": "Merino wool",
        "percentage": 100
      }
    ],
    "substances_of_concern": [
      "None above threshold"
    ],
    "gtin": "02000000000053"
  }
}

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

Einen JSON Merge Patch auf einen Produktpass anwenden.

patch/organizations/{organization}/passports/{id}

Scope: passports:write
Idempotency-Key: Wird 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.

Anfrage-Header

Expected-VersionGanzzahlOptional

Die version des Produktpasses, den Sie gelesen haben, als Ganzzahl. Hat sich der Produktpass zwischenzeitlich geändert, wird der Schreibvorgang mit precondition_failed abgelehnt — der einzige Weg, ein Lesen-Ändern-Schreiben gegen einen gleichzeitig arbeitenden Bearbeiter abzusichern. Verwenden Sie diesen Header statt If-Match. Wiederholen Sie einen abgelehnten Schreibvorgang mit einem NEUEN Idempotency-Key: Die Ablehnung ist unter dem alten gespeichert und würde erneut ausgeliefert.

If-MatchZeichenketteOptional

ABGELEHNT mit invalid_request, sofern er nicht genau * lautet — insbesondere also, sobald er ein ETag enthält. Unser CDN vergleicht If-Match mit der ANTWORT und schreibt das Ergebnis um: Ein bedingter Schreibvorgang würde also ausgeführt und Ihnen trotzdem als 412 gemeldet — die Ablehnung verhindert genau das. Senden Sie die Version stattdessen als Expected-Version. If-Match: *, das nur verlangt, dass der Produktpass noch besteht, wird akzeptiert.

Anfragekörper

dataObjektOptional

Ein RFC 7386 JSON Merge Patch, der auf den Inhalt des Produktpasses angewendet wird. Lassen Sie einen Schlüssel weg, bleibt er unangetastet; senden Sie null, um ihn zu löschen. Arrays werden ersetzt, niemals zusammengeführt.

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" \
  -X PATCH \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "recycled_content_percentage": 38,
    "recycling_instructions": "Return to any Atelier Kestrel store for fibre recovery."
  }
}'

Antwort · 200

{
  "object": "passport",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "category": "textile",
  "status": "draft",
  "gtin": null,
  "serial_number": null,
  "external_id": "SKU-4471-BLK",
  "version": 2,
  "livemode": true,
  "registry_id": null,
  "created_at": "2026-08-01T09:12:44.918Z",
  "updated_at": "2026-08-01T10:44:12.700Z",
  "published_at": null,
  "trashed_at": null,
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR",
    "material_composition": [
      {
        "fiber": "Merino wool",
        "percentage": 100
      }
    ],
    "substances_of_concern": [
      "None above threshold"
    ],
    "recycled_content_percentage": 38,
    "recycling_instructions": "Return to any Atelier Kestrel store for fibre recovery."
  }
}

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

Einen Produktpass veröffentlichen.

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

Scope: passports:write
Idempotency-Key: Wird 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.

Anfragekörper

variant_review_fingerprintZeichenketteOptional

Erforderlich, wenn der Produktpass Größen und Farben enthält, die ein Assistent eingetragen hat: der Fingerabdruck aus GET …/variants/review, gesendet nachdem eine Person diese Zeilen geprüft hat. Ohne ihn wird die Veröffentlichung mit variant_review_required abgelehnt; haben sich die Größen und Farben nach der Prüfung geändert, mit variant_review_changed. Senden Sie ihn mit einem neuen Idempotenzschlüssel. Eine hexadezimale Zeichenkette mit 64 Zeichen.

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/publish" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Antwort · 200

{
  "object": "passport",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "category": "textile",
  "status": "published",
  "gtin": "02000000000053",
  "serial_number": null,
  "external_id": "SKU-4471-BLK",
  "version": 4,
  "livemode": true,
  "registry_id": null,
  "created_at": "2026-08-01T09:12:44.918Z",
  "updated_at": "2026-08-01T14:03:22.501Z",
  "published_at": "2026-08-01T14:03:22.501Z",
  "trashed_at": null,
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR",
    "material_composition": [
      {
        "fiber": "Merino wool",
        "percentage": 100
      }
    ],
    "substances_of_concern": [
      "None above threshold"
    ],
    "gtin": "02000000000053"
  },
  "warnings": [
    {
      "code": "environmental_claim_detected",
      "message": "This passport contains environmental claims (carbon neutral), found in its wording or in fields the brand marked as environmental information. From 27 September 2026, Directive (EU) 2024/825 requires the trader placing the product on the market to hold substantiation for such claims. Publishing succeeded; confirm the substantiation exists.",
      "doc_url": "https://passportcraft.com/docs/api/errors#environmental_claim_detected"
    }
  ]
}

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

Einen Produktpass zurückziehen.

Destruktiv

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

Scope: passports:write
Idempotency-Key: Wird 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.

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/unpublish" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Antwort · 200

{
  "object": "passport",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "category": "textile",
  "status": "draft",
  "gtin": "02000000000053",
  "serial_number": null,
  "external_id": "SKU-4471-BLK",
  "version": 5,
  "livemode": true,
  "registry_id": null,
  "created_at": "2026-08-01T09:12:44.918Z",
  "updated_at": "2026-08-02T08:15:09.113Z",
  "published_at": null,
  "trashed_at": null,
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR",
    "material_composition": [
      {
        "fiber": "Merino wool",
        "percentage": 100
      }
    ],
    "substances_of_concern": [
      "None above threshold"
    ],
    "gtin": "02000000000053"
  }
}

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

Einen Produktpass in den Papierkorb verschieben.

Destruktiv

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

Scope: passports:write
Idempotency-Key: Wird 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.

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/trash" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Antwort · 200

{
  "object": "passport",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "category": "textile",
  "status": "trashed",
  "gtin": "02000000000053",
  "serial_number": null,
  "external_id": "SKU-4471-BLK",
  "version": 6,
  "livemode": true,
  "registry_id": null,
  "created_at": "2026-08-01T09:12:44.918Z",
  "updated_at": "2026-08-02T08:19:44.002Z",
  "published_at": null,
  "trashed_at": "2026-08-02T08:19:44.002Z",
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR",
    "material_composition": [
      {
        "fiber": "Merino wool",
        "percentage": 100
      }
    ],
    "substances_of_concern": [
      "None above threshold"
    ],
    "gtin": "02000000000053"
  }
}

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

Einen Produktpass aus dem Papierkorb wiederherstellen.

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

Scope: passports:write
Idempotency-Key: Wird 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.

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/restore" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Antwort · 200

{
  "object": "passport",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "category": "textile",
  "status": "draft",
  "gtin": "02000000000053",
  "serial_number": null,
  "external_id": "SKU-4471-BLK",
  "version": 7,
  "livemode": true,
  "registry_id": null,
  "created_at": "2026-08-01T09:12:44.918Z",
  "updated_at": "2026-08-02T08:21:03.884Z",
  "published_at": null,
  "trashed_at": null,
  "data": {
    "product_name": "Merino Crew Neck",
    "product_description": "Mid-weight knitted crew neck in 100% merino wool.",
    "manufacturer_name": "Atelier Kestrel SAS",
    "manufacturer_address": "14 rue des Tanneurs, 59100 Roubaix",
    "manufacturer_country": "FR",
    "material_composition": [
      {
        "fiber": "Merino wool",
        "percentage": 100
      }
    ],
    "substances_of_concern": [
      "None above threshold"
    ],
    "gtin": "02000000000053"
  }
}

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

Einen Produktpass gegen sein Kategorieschema prüfen, ohne zu speichern.

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

Scope: passports: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.

Anfragekörper

dataObjektOptional

Felder, die vor der Prüfung eingemischt werden, sodass Sie eine Änderung testen können, ohne sie zu speichern. Geschrieben wird in keinem der beiden Fälle etwas.

variant_review_fingerprintZeichenketteOptional

Der Fingerabdruck aus GET …/variants/review. Senden Sie ihn, um zu fragen, ob die Veröffentlichung mit diesem Fingerabdruck gelingen würde; ohne ihn meldet ein Produktpass mit von einem Assistenten eingetragenen Größen und Farben die Prüfung als Fehler. Eine hexadezimale Zeichenkette mit 64 Zeichen; ein veralteter oder fehlerhafter Wert wird als Befund gemeldet statt abgelehnt, da dieser Endpunkt eine Vorhersage liefert.

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/validate" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "material_composition": null
  }
}'

Antwort · 200

{
  "object": "validation",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/validation",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "category": "textile",
  "schema_version": "1.0.0-draft",
  "dry_run": true,
  "valid": false,
  "publishable": false,
  "error_count": 2,
  "warning_count": 0,
  "checked_at": "2026-08-02T08:26:11.409Z",
  "issues": [
    {
      "object": "validation_issue",
      "field": "material_composition",
      "source": {
        "pointer": "/data/material_composition"
      },
      "rule": "required",
      "severity": "error",
      "message": "Material Composition is required",
      "message_key": "required",
      "message_params": {
        "field": "Material Composition"
      },
      "writable_via_api": true
    },
    {
      "object": "validation_issue",
      "field": "gtin",
      "source": {
        "pointer": "/data/gtin"
      },
      "rule": "required",
      "severity": "error",
      "message": "A GTIN is required before this passport can be published. A saved size or colour with its own barcode also satisfies this.",
      "writable_via_api": true
    }
  ]
}

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

Öffentliche URLs und GS1 Digital Links abrufen. gs1_digital_links enthält alle Varianten mit variant_id, size und colour. Die URI der eigenen Haupt-GTIN erscheint einmal mit den Variantendaten; eine Haupt-URI mit Seriennummer bleibt separat.

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

Scope: passports: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.

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/links" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Antwort · 200

{
  "object": "passport_links",
  "id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/links",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "status": "published",
  "livemode": true,
  "gtin": "02000000000053",
  "serial_number": null,
  "public_url": "https://passportcraft.com/passport/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "qr_target": "https://passportcraft.com/01/02000000000053",
  "gs1_digital_links": [
    {
      "uri": "https://passportcraft.com/01/02000000000053",
      "gtin14": "02000000000053",
      "serial": null,
      "linkset_url": "https://passportcraft.com/01/02000000000053?linkType=linkset",
      "unavailable_reason": null,
      "variant_id": null,
      "size": null,
      "colour": null
    }
  ],
  "gs1_digital_link": {
    "uri": "https://passportcraft.com/01/02000000000053",
    "gtin14": "02000000000053",
    "serial": null,
    "linkset_url": "https://passportcraft.com/01/02000000000053?linkType=linkset",
    "unavailable_reason": null
  },
  "resolves_publicly": true,
  "not_resolvable_reason": null,
  "preview_url": null
}

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

Batteriemesswerte auflisten.

get/organizations/{organization}/passports/{id}/units/{unitId}/readings

Scope: units: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.

unitIdZeichenkettePflicht

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

Abfrageparameter

limitZeichenketteOptional

Anzahl der zurückzugebenden Messwerte, von 1 bis 100.

cursorZeichenketteOptional

Der next_cursor der vorherigen Seite. Behalten Sie denselben Feldfilter bei.

fieldZeichenketteOptional

Nur Messwerte für dieses Feld zurückgeben.

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/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84/readings?field=status&limit=50" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Antwort · 200

{
  "object": "list",
  "data": [
    {
      "object": "unit_reading",
      "id": "a1100000-0000-4000-8000-000000000001",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84/readings/a1100000-0000-4000-8000-000000000001",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "passport_id": "b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "unit_id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
      "unit": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "livemode": true,
      "field": "status",
      "value": "original",
      "observed_on": "2026-08-02",
      "source": "brand_statement",
      "note": null,
      "document_id": null,
      "recorded_by": "a1100000-0000-4000-8000-000000000002",
      "recorded_actor_type": "api_key",
      "recorded_via": "api",
      "recorded_at": "2026-08-02T09:31:18.446123Z",
      "legacy_import": false
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84/readings?field=status&limit=50

Batteriemesswert erfassen.

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

Scope: units: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.

unitIdZeichenkettePflicht

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

Anfragekörper

fieldZeichenkettePflicht

Ein batterieseitiges Feld aus dem Kategorieschema.

valueZeichenkette, Zahl oder Zahl mit EinheitPflicht

Ein Wert gemäß Felddefinition; bei Feldern mit Einheitenauswahl Zahl und Einheit.

observed_onZeichenkettePflicht

Datum der Messung oder Angabe im Format JJJJ-MM-TT.

sourceZeichenkettePflicht

measurement oder brand_statement.

noteZeichenketteOptional

Optionaler Hinweis zu Methode oder Nachweis, bis zu 500 Zeichen.

document_idZeichenketteOptional

Optionales Dokument aus der Organisationsbibliothek, das diesen Messwert belegt.

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/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84/readings" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "field": "status",
  "value": "original",
  "observed_on": "2026-08-02",
  "source": "brand_statement"
}'

Antwort · 201

{
  "object": "unit_reading",
  "id": "a1100000-0000-4000-8000-000000000001",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84/readings/a1100000-0000-4000-8000-000000000001",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "passport_id": "b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
  "unit_id": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
  "passport": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04",
  "unit": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84",
  "livemode": true,
  "field": "status",
  "value": "original",
  "observed_on": "2026-08-02",
  "source": "brand_statement",
  "note": null,
  "document_id": null,
  "recorded_by": "a1100000-0000-4000-8000-000000000002",
  "recorded_actor_type": "api_key",
  "recorded_via": "api",
  "recorded_at": "2026-08-02T09:31:18.446123Z",
  "legacy_import": false
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/b6f0d4a2-71c3-4e58-8a19-3f7c2d5e8b04/units/d41d8cd9-8f00-4b20-a204-9800998ecf84/readings

Ein Dokument von einem Pass lösen und aus der Bibliothek löschen, wenn es nirgends mehr verwendet wird.

delete/organizations/{organization}/passports/{id}/documents/{documentId}

Scope: documents:write
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.

documentIdZeichenkettePflicht

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

Anfrage-Header

If-MatchZeichenketteOptional

ABGELEHNT mit invalid_request, sofern er nicht genau * lautet. Dieser Endpunkt hat keine bedingte Form. DELETE ist die einzige Methode, die wir nicht gegen unser CDN gemessen haben; dieses vergleicht If-Match auf manchen Pfaden mit der ANTWORT und schreibt einen Erfolg in einen 412 um — und ein bereits ausgeführtes Lösen der Verknüpfung darf Ihnen niemals als Ablehnung gemeldet werden. If-Match: *, das nur verlangt, dass das Dokument noch besteht, wird akzeptiert.

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/a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b" \
  -X DELETE \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Antwort · 200

{
  "object": "document.deleted",
  "id": "a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
  "livemode": true,
  "detached": true,
  "deleted_from_library": true,
  "remaining_links": 0,
  "document_limit": 50
}

DELETE /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41/documents/a3b8c2d1-5e64-4f79-8a0b-1c2d3e4f5a6b