TracePass
Loslegen
Pässe

Wirtschaftsakteurs-Partei upsert

Erstellt oder ersetzt die Party für eine Rolle auf einem Pass. Das Pfad-Segment role bestimmt den Slot — `manufacturer`, `importer`, `authorisedRepresentative`, `distributor`, `recycler`, `producerResponsibilityOrg`. Zweimaliges Senden derselben Rolle ist ein Upsert: der bestehende Block wird atomar ersetzt.

PATCH/api/v1/passports/{id}/parties/{role}
OpenAPI 3.1 herunterladen
PATCH/api/v1/passports/{id}/parties/{role}

Wirtschaftsakteurs-Partei upsert

Erstellt oder ersetzt die Party für eine Rolle auf einem Pass. Das Pfad-Segment role bestimmt den Slot — `manufacturer`, `importer`, `authorisedRepresentative`, `distributor`, `recycler`, `producerResponsibilityOrg`. Zweimaliges Senden derselben Rolle ist ein Upsert: der bestehende Block wird atomar ersetzt.

Mindestens eines von `gln`, `legacyOperatorId` oder `operatorIdentifier` muss gesetzt sein — ohne Identifier identifiziert die Party niemanden. `operatorIdentifier` trägt einen schema-getaggten strukturierten Identifier gemäß EN 18219 §6.2–6.5 (iso6523, gln, did, doi). Wenn das Schema `gln` ist, befüllt es auch das Top-Level-Feld `gln`; wenn beide gesetzt sind, müssen sie übereinstimmen (400 mit Pfad `operatorIdentifier`). `facilityIdentifier` verwendet dieselben Schemata und identifiziert den Standort des Betreibers — befüllt `gln` nie. Typisierte Identifier werden nicht durch KI-Extraktion oder CSV-Import gesetzt.

Zählt als ein v1-Schreibvorgang. Unterstützt Idempotency-Key. Die Batterieverordnung verlangt mindestens { manufacturer, importer (wenn anwendbar), recycler }, bevor ein Pass akzeptiert wird; der Regulatory-Completeness-Scorecard zeigt fehlende Rollen im Dashboard an. Das passende `DELETE /api/v1/passports/{id}/parties/{role}` entfernt eine Rolle idempotent.

Pfad-Parameter

  • iderforderlich

    ObjectId

    Pass-ID.

    e.g. 6650b2c3d4e5f6a7b8c9d0e1

  • roleerforderlich

    enum

    Einer von: `manufacturer`, `importer`, `authorisedRepresentative`, `distributor`, `recycler`, `producerResponsibilityOrg`. Andere Rollen liefern 400 zurück.

    e.g. recycler

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 pro logischer Operation.

Body-Felder

  • legalNameerforderlich

    string (1-200 chars)

    Name der juristischen Person wie im Handelsregister. Erforderlich — eine Party ohne Namen hilft keinem Procurement-Leser, unabhängig vom getragenen Identifier.

    e.g. EuroBat Recyclers GmbH

  • gln

    string (13 digits)

    GS1 Global Location Number mit gültiger Mod-10-Prüfziffer. Dringend empfohlen — wenn zwei Rollen dieselbe `gln` teilen, gibt das JSON-LD eine einzelne Partei mit beiden Rollen aus. Muss als echte GLN validieren; partielle / nur-Ziffern-Strings liefern 400.

    e.g. 4012345678901

  • country

    string (ISO 3166-1 alpha-2)

    Zweibuchstabiger Großbuchstaben-Ländercode — z. B. `DE`, `BG`, `FR`.

    e.g. DE

  • legacyOperatorId

    string (1-120 chars)

    Free-Text-Fallback-Identifier für Parteien ohne GLN — USt-IdNr., EORI, Lieferantencode oder eine interne ID Ihres ERP. Erforderlich, wenn `gln` ausgelassen wird.

    e.g. DE123456789

  • url

    string (URL, max 500 chars)

    Organisationsseite — typischerweise die Unternehmenswebsite oder eine Corporate-Info-Unterseite.

    e.g. https://eurobat-recyclers.example

  • operatorIdentifier

    object (EN 18219 §6.2–6.5)

    Strukturierter Betreiber-Identifier nach EN 18219 §6.2–6.5. Erfordert `scheme` sowie schemaspezifische Felder. Schemata: `iso6523` — ICD (4-stelliger ISO/IEC 6523-Code, z. B. 0199 = LEI, 0088 = GLN, 0060 = DUNS) + `value`; `gln` — 13-stellige GLN (füllt auch das Top-Level-Feld `gln`; müssen übereinstimmen, wenn beide gesetzt); `did` — DID-URI in `did:<method>:<id>`-Form (nur Syntaxprüfung, EN 18219 §6.4.2(b)); `doi` — DOI in `10.<registrant>/<suffix>`-Form (Präfix `doi:` / `https://doi.org/` wird akzeptiert und entfernt). Nicht durch KI-Extraktion oder CSV-Import gesetzt.

    e.g. { "scheme": "iso6523", "icd": "0199", "value": "529900T8BM49AURSDO55" }

  • facilityIdentifier

    object (EN 18219 §6.2–6.5)

    Strukturierter Standort-Identifier nach EN 18219 §6.2–6.5 — identifiziert den Standort des Betreibers, nicht den Betreiber selbst. Verwendet dieselben vier Schemata wie `operatorIdentifier`; die `gln`-Variante akzeptiert zusätzlich `extension` (GS1-SGLN-Teilstandortcode). Befüllt das Top-Level-Feld `gln` nie. Nicht durch KI-Extraktion oder CSV-Import gesetzt.

    e.g. { "scheme": "gln", "gln": "4012345678901", "extension": "1" }

Anfrage

curl -sS -X PATCH \
  https://app.tracepass.eu/api/v1/passports/6650b2c3d4e5f6a7b8c9d0e1/parties/recycler \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "legalName": "EuroBat Recyclers GmbH",
    "gln": "4012345678901",
    "country": "DE",
    "url": "https://eurobat-recyclers.example"
  }'

Antwort

{
  "role": "recycler",
  "party": {
    "legalName": "EuroBat Recyclers GmbH",
    "gln": "4012345678901",
    "country": "DE",
    "url": "https://eurobat-recyclers.example",
    "status": "active"
  },
  "version": 5
}

Verwandte Endpoints