Erste Schritte mit der PassportCraft API

Erste Schritte

Fünf Anfragen vom leeren Konto bis zum veröffentlichten Produktpass mit öffentlichem Link.

1.API-Schlüssel anlegen
Schlüssel werden in den Einstellungen erzeugt. Ein Schlüssel wird genau einmal angezeigt, im Moment seiner Erzeugung; danach bleibt nur seine Kennung sichtbar.
Vergeben Sie nur die Scopes, die die Integration wirklich braucht. Ein Schlüssel, der Produktpässe lesen, aber nicht veröffentlichen darf, kann keinen Katalog versehentlich live schalten.
API-Schlüssel in den Einstellungen öffnen
shell
```
export PASSPORTCRAFT_API_KEY=pc_sk_test_…
```

2.Zugangsschlüssel prüfen

Die erste sinnvolle Anfrage. Sie bestätigt, dass der Schlüssel funktioniert, meldet ob es sich um einen Live- oder einen Test-Zugang handelt, und listet die Organisationen auf, für die er handeln darf — samt der Organisations-ID, die jede weitere Anfrage benötigt.

Anfrage

curl "https://passportcraft.com/api/v1/whoami" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Antwort

{
  "object": "credential",
  "key_id": "K3n9Qw2P",
  "livemode": true,
  "owner_organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "expires_at": null,
  "last_used_at": "2026-08-02T07:41:03.220Z",
  "organizations": [
    {
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "scopes": [
        "passports:read",
        "passports:write",
        "units:read",
        "units:write"
      ],
      "granted_at": "2026-07-14T11:02:19.004Z"
    }
  ]
}

Vollständige Referenz zu diesem Endpunkt

3.Produktpass erstellen

Ein Produktpass entsteht als Entwurf. Pflicht ist allein die Kategorie; das Dokument lässt sich danach Feld für Feld füllen, genau wie im Editor.

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

{
  "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"
    ]
  }
}

Vollständige Referenz zu diesem Endpunkt

4.Vor dem Veröffentlichen prüfen

Die Prüfung schreibt nichts. Sie meldet, was eine Veröffentlichung blockieren würde und was nur ein Hinweis ist — die Integration erfährt es also vor der Anfrage, auf die es ankommt.

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

{
  "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
    }
  ]
}

Vollständige Referenz zu diesem Endpunkt

5.Veröffentlichen

Mit dem Veröffentlichen wird der Produktpass für jeden lesbar, der ihn scannt. Die Anfrage wird abgelehnt, wenn ein Pflichtfeld fehlt, die GTIN fehlt oder der Tarif keinen freien Veröffentlichungsplatz mehr hat.

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

{
  "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"
    }
  ]
}

Vollständige Referenz zu diesem Endpunkt

6.Öffentlichen Link abrufen

Liefert die öffentliche Seite, den GS1 Digital Link und genau das Ziel, das ein gedruckter QR-Code kodiert — der Wert, der an die Etikettendruckerei geht. Zusätzlich liefert die Antwort preview_url: eine Adresse, die ein angemeldetes Mitglied Ihrer Organisation öffnen kann. Sie ist gefüllt, solange der Produktpass öffentlich nicht auflösbar ist — bei einem Test-Produktpass ist das immer so — und leer, sobald er öffentlich auflöst. Mit einem Test-Zugang zeigt sie die Produktseite so, wie sie die Kundschaft sieht, unter einem Balken, der sie als Test-Produktpass kennzeichnet.

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

{
  "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
}

Vollständige Referenz zu diesem Endpunkt

Wie es weitergeht

Konventionen — Wiederholungen, Blätterung und bedingte Schreibvorgänge.
Fehler — der Code, auf den bei einer Ablehnung verzweigt wird.
Kompatibilität — was sich ohne Ankündigung ändern darf und was nicht.

1.API-Schlüssel anlegen

2.Zugangsschlüssel prüfen

3.Produktpass erstellen

4.Vor dem Veröffentlichen prüfen

5.Veröffentlichen

6.Öffentlichen Link abrufen

Wie es weitergeht