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. Der Pass wird als Entwurf angelegt, und ein Entwurf belegt keinen Platz im maxDpps-Limit Ihres Plans. Das Anlegen liefert daher nie einen Overage-Fehler und löst keine Gebühr aus. Das Plan-Limit und eine etwaige Pro-Pass-Overage-Gebühr greifen erst, wenn der Pass im Dashboard veröffentlicht wird.

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

    string (24 hex chars)

    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.

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