Schnellstart

Fünf Minuten von der Registrierung bis zu einem Digitalen Produktpass im Status draft. Diese Anleitung zeigt das kleinstmögliche funktionierende Beispiel — ein Produkt, ein Pass, keine Parties, keine Webhooks. Ergänzen Sie diese, nachdem Sie den Round-Trip einmal gesehen haben.

Vorbereitung

Sie benötigen einen TracePass-Workspace auf jedem Plan, auch Free — v1-API-Zugriff ist in jedem Tier verfügbar; nur das tägliche Aufrufkontingent unterscheidet sich (Free 100, Basic 200, Starter 350, Growth 500, Scale 1.000, Pro 2.000, Enterprise unbegrenzt). Registrieren Sie sich unter app.tracepass.eu/register, dann kehren Sie hierher zurück. Die Beispiele unten gehen von der Produktions-Base-URL https://app.tracepass.eu aus; ersetzen Sie sie durch Ihren eigenen Host, falls Sie self-hosted laufen.

1. API-Schlüssel erzeugen

1. Öffnen Sie Developer → API keys im Dashboard.
2. Klicken Sie auf New key, vergeben Sie ein Label („Quickstart“ passt) und kopieren Sie das Secret. Schlüssel beginnen mit dem Präfix tp_, gefolgt von einem opaken Zufallssuffix — speichern Sie sie in Ihrem Secret Manager, nicht in der Versionskontrolle.
3. Jeder API-Aufruf trägt den Schlüssel als Bearer Token im Standard-Authorization-Header. Wir maskieren ihn unten überall alstp_REDACTED_xxxxxxxxxxxx.

2. Produkt anlegen

Pässe gehören immer zu einem Produkt, und ein Produkt ist an eine Kategorienvorlage gebunden, die Feldvalidierung, JSON-LD-Ausgabe und das Rendering des öffentlichen Viewers steuert. Kategorien sind gesäht — wählen Sie den Slug, der zu Ihrer Ware passt. Für Batterien ist es batteries; für Textilien textiles; für Schmuck jewelry. Die vollständige Liste steht im öffentlichen Buyer's Guide.

curl -sS https://app.tracepass.eu/api/v1/products \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "48V Li-Ion Pack",
    "model": "BP-48V-100",
    "category": "batteries"
  }'

Die 201-Antwort enthält ein _id — das ist Ihr Produkt-Handle. Behalten Sie es für Schritt 3.

3. Pass anlegen

Ein Pass ist eine serialisierte Einheit eines Produkts. Setzen Sie productId auf das soeben erstellte Produkt, liefern Sie eine 14-stellige GS1-GTIN (mit gültiger Prüfziffer) plus eine innerhalb der GTIN eindeutige Seriennummer. Der Pass materialisiert sich im Status draft — Felder werden über den per-field PATCH-Endpoint befüllt, dann wird der Pass nach Abschluss der Prüfung über das Dashboard veröffentlicht.

curl -sS https://app.tracepass.eu/api/v1/passports \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "6650a1b2c3d4e5f6a7b8c9d0",
    "gs1": {
      "gtin": "04012345000015",
      "serialNumber": "BP-48V-100-000001"
    }
  }'

Die 201-Antwort liefert gs1.digitalLinkUri — die GS1-Digital-Link-URL, die Sie schon heute in einen QR-Code kodieren können, noch vor der Veröffentlichung des Passes. Bis zur Veröffentlichung gibt die URL einen 503-Placeholder zurück; danach liefert sie den öffentlichen Viewer (HTML standardmäßig, application/ld+json bei Content Negotiation).

4. QR-Code scannen

Nachdem Sie Felder befüllt und den Pass über das Dashboard veröffentlicht haben, öffnen Sie gs1.digitalLinkUri im Browser — genau das würde ein Endverbraucher oder ein regulatorischer Mobilscanner sehen. Dieselbe URL mit Accept: application/ld+json liefert das JSON-LD-Dokument für maschinelle Konsumenten (Prüfer, EPREL-Ingestion, das kommende EU-DPP-Register).

curl -sSL https://id.tracepass.eu/p/01/04012345000015/21/BP-48V-100-000001 \
  -H "Accept: application/ld+json"

Wie geht es weiter

Sie haben jetzt einen Pass. Die zwei Folgeschritte, die die meisten Teams als Nächstes umsetzen, sind: (a) Wirtschafts­ akteure (parties) anhängen, damit die Pflichtrollen-Prüfung des Regulators besteht — siehe den Endpoint Upsert party; (b) einen Webhook verdrahten, damit Ihr ERP von Lebenszyklus-Änderungen erfährt (Veröffentlichung, Suspendierung, Archivierung) — siehe den Abschnitt Webhooks.