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 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 <api-key>`. Schlüssel erzeugen Sie unter Developer → API keys (jeder Plan einschließlich Free; tägliches Aufrufkontingent skaliert mit dem Plan).

    e.g. Bearer tp_REDACTED_xxxxxxxxxxxx

  • Idempotency-Key

    string

    UUID v4 (oder ein beliebiger opaker String ≤ 255 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

  • gs1.gtinerforderlich

    string (14 digits)

    GTIN-14 mit gültiger GS1-Prüfziffer. Darf noch nicht von einem anderen Tenant registriert sein.

    e.g. 04012345000015

  • gs1.serialNumbererforderlich

    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.

  • 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": "04012345000015",
      "serialNumber": "BP-48V-100-000001"
    }
  }'

Antwort

{
  "_id": "6650b2c3d4e5f6a7b8c9d0e1",
  "companyId": "6650a0b1c2d3e4f5a6b7c8d9",
  "productId": "6650a1b2c3d4e5f6a7b8c9d0",
  "templateId": "6650a1b2c3d4e5f6a7b8c9d1",
  "gs1": {
    "gtin": "04012345000015",
    "serialNumber": "BP-48V-100-000001",
    "digitalLinkUri": "https://id.tracepass.eu/p/01/04012345000015/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