TracePass
Loslegen
Pässe

Pass anlegen

Erstellt einen einzelnen Digitalen Produktpass. Der Pass ist an ein Produkt gebunden (productId) und durch eine GS1 GTIN + eine innerhalb dieser GTIN eindeutige Seriennummer identifiziert. Neue Pässe starten im Status `draft` — Felder werden über nachfolgende PATCH-Aufrufe befüllt und der Pass wird nach Abschluss der Prüfung über das Dashboard veröffentlicht.

POST/api/v1/passports
OpenAPI 3.1 herunterladen
POST/api/v1/passports

Pass anlegen

Erstellt einen einzelnen Digitalen Produktpass. Der Pass ist an ein Produkt gebunden (productId) und durch eine GS1 GTIN + eine innerhalb dieser GTIN eindeutige Seriennummer identifiziert. Neue Pässe starten im Status `draft` — Felder werden über nachfolgende PATCH-Aufrufe befüllt und der Pass wird nach Abschluss der Prüfung über das Dashboard veröffentlicht.

GTIN muss 14 Ziffern (oder eine 13-stellige EAN, auf 14 aufgefüllt) mit gültiger GS1-Prüfziffer haben und darf noch keinem anderen Tenant zugeordnet sein. Zählt als ein v1-Schreibvorgang UND verbraucht einen DPP-Slot aus dem `maxDpps`-Kontingent Ihres Plans — wenn dieses Kontingent ausgeschöpft ist und Ihr Plan Overage unterstützt, gibt der Aufruf 402 mit einem `overage_required`-Body zurück; wiederholen Sie mit `confirmOverage: true`, um die Pro-Pass-Gebühr zu akzeptieren.

Unterstützt den optionalen Idempotency-Key-Header — die Plattform spielt die ursprüngliche 201-Antwort 24 Stunden lang für denselben Schlüssel zurück.

Header

  • Authorizationerforderlich

    string

    `Bearer <token>` — entweder ein `tp_` API-Schlüssel (Developer → API Keys; am einfachsten, für Server-zu-Server) oder ein OAuth-2.0-Access-Token (Developer → OAuth Apps; für nutzerautorisierte Apps, scoped und widerrufbar). Die Authentication-Seite enthält den vollständigen OAuth-Flow und die Scope-Liste.

    e.g. Bearer tp_REDACTED_xxxxxxxxxxxx

  • Idempotency-Key

    string

    UUID v4 (oder ein beliebiger opaker String ≤ 64 Zeichen) pro logischer Operation. Die erste Antwort wird 24 Stunden lang zurückgespielt.

Body-Felder

  • productIderforderlich

    ObjectId

    ID des Produkts, zu dem der Pass gehört. Muss zur Firma des API-Schlüssels gehören.

    e.g. 6650a1b2c3d4e5f6a7b8c9d0

  • identifier

    ProductIdentifier

    EN 18219 schemamarkierter Identifier. Genau eines von `identifier` oder dem Legacy-`gs1`-Block ist erforderlich. Akzeptiert fünf Schemata: `gs1` (GTIN + Seriennummer), `iso15459` (Nicht-GS1-Agentur-ID), `iec61406` (IEC Identification Link URI), `did` (W3C DID), `doi` (Digital Object Identifier). Für `doi` ist `granularity` ERFORDERLICH — muss `"model"`, `"batch"` oder `"item"` sein (EN 18219 §5.6.2(b): ein DOI muss angeben, ob er das Produktmodell, eine Produktionscharge oder ein einzelnes Exemplar identifiziert). Batteriepässe akzeptieren nur `gs1` und `iso15459`; `iec61406`, `did` und `doi` werden gemäß Art. 77(3) der Batterieverordnung abgelehnt, der einen ISO/IEC 15459-basierten Identifier vorschreibt.

  • gs1.gtin

    string (14 digits, or 13-digit EAN)

    GTIN-14 mit gültiger GS1-Prüfziffer. Teil des Legacy-`gs1`-Blocks — für neue Integrationen bevorzugen Sie `identifier` mit `scheme: "gs1"`. Darf nicht bereits von einem anderen Tenant registriert sein.

    e.g. 04012345000016

  • gs1.serialNumber

    string (1-100 chars)

    Innerhalb der GTIN eindeutige Seriennummer. Üblich: Produktmodell + Sequenz (BP-48V-100-000001).

    e.g. BP-48V-100-000001

  • parties

    Record<role, Party>

    Optionaler struktureller Parties-Block. Eine nach Rolle indizierte Karte — `manufacturer`, `importer`, `authorisedRepresentative`, `distributor`, `recycler`, `producerResponsibilityOrg`. Jeder Wert ist eine Party. Siehe Upsert-Party-Endpoint für die Body-Form pro Party. Rollen können auch nach der Erstellung via PATCH /api/v1/passports/{id}/parties/{role} hinzugefügt oder ersetzt werden.

  • lineage

    LineageInput

    Nur für Batteriepässe. Eine Batterie, die zur Wiederverwendung oder zur Umnutzung vorbereitet, umgenutzt oder wiederaufgearbeitet wurde, braucht einen neuen Batteriepass, der mit dem Batteriepass bzw. den Batteriepässen der ursprünglichen Batterie verknüpft ist (Art. 77 Abs. 7 der Batterieverordnung). Senden Sie `{ predecessors: [ { internalPassportId | identifier, trigger } ] }` mit bis zu 10 Vorgängern: `internalPassportId` für einen eigenen Pass, `identifier` (sein auflösbarer URI) für jeden anderen. `trigger` ist `preparation_for_reuse`, `preparation_for_repurposing`, `repurposing` oder `remanufacturing`. `batteryStatus` wird aus diesen Werten abgeleitet, der Block ist nach dem Anlegen unveränderlich, und Ihre eigenen ursprünglichen Pässe erhalten einen `successors`-Verweis. Eine vor dem 18. Februar 2027 in Verkehr gebrachte Batterie hat keinen ursprünglichen Pass: Senden Sie eine leere Liste mit `noPredecessorReason`. Regelverstöße liefern 422 mit dem Regelcode in `error`, z. B. `duplicate_predecessor`, `predecessor_not_found`, `status_trigger_mismatch`.

  • confirmOverage

    boolean

    Akzeptiert die Pro-Pass-Overage-Gebühr, wenn das `maxDpps`-Kontingent des Plans bereits ausgeschöpft ist. Nur erforderlich nach einer 402-Antwort auf einen vorherigen Versuch.

Anfrage

curl -sS https://app.tracepass.eu/api/v1/passports \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Idempotency-Key: 7b4f1e2c-9a3d-4e5b-8c1a-2d3e4f5a6b7c" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "6650a1b2c3d4e5f6a7b8c9d0",
    "gs1": {
      "gtin": "04012345000016",
      "serialNumber": "BP-48V-100-000001"
    }
  }'

Antwort

{
  "_id": "6650b2c3d4e5f6a7b8c9d0e1",
  "companyId": "6650a0b1c2d3e4f5a6b7c8d9",
  "productId": "6650a1b2c3d4e5f6a7b8c9d0",
  "templateId": "6650a1b2c3d4e5f6a7b8c9d1",
  "gs1": {
    "gtin": "04012345000016",
    "serialNumber": "BP-48V-100-000001",
    "digitalLinkUri": "https://id.tracepass.eu/p/01/04012345000016/21/BP-48V-100-000001"
  },
  "status": "draft",
  "completionPercentage": 32,
  "fieldCounts": {
    "total": 52,
    "empty": 35,
    "approved": 17,
    "pendingReview": 0,
    "flagged": 0
  },
  "fields": { "...": "...seeded from product defaults + template defaults + company prefill..." },
  "createdAt": "2026-05-09T10:00:00.000Z"
}

Verwandte Endpoints