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.

Ein LEI (iso6523 mit ICD 0199) wird gegen das GLEIF-Register geprüft. Kennt GLEIF ihn nicht oder meldet ihn als ANNULLED oder DUPLICATE, lautet die Antwort 400 (bei einem Duplikat nennt die Meldung den zu verwendenden LEI). Ein LEI mit Status LAPSED oder RETIRED oder einer inaktiven Einheit sowie ein legalName, der keinem der GLEIF-Namen dieses LEI entspricht, wird gespeichert und in einem warnings-Array der Antwort gemeldet.

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.

Sobald ein Batteriepass in Verkehr gebracht ist, antwortet ein Schreibvorgang, der einen gespeicherten operatorIdentifier oder facilityIdentifier ändern würde, mit 409 operator_locked (keys nennt <role>.<field>); andere Änderungen an Parteien bleiben erlaubt. Zur Korrektur einer gesperrten Kennung markieren Sie den Pass zur Löschung und legen einen neuen an.

Pfad-Parameter

  • iderforderlich

    string (24 hex chars)

    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

  • tradeName

    string (max 200 chars)

    Eingetragener Handelsname oder eingetragene Handelsmarke. Für einen Batterie-Einführer ist das eine der Angaben, die er auf der Batterie macht (Batterieverordnung Art. 41 Abs. 3); die Konformitätsprüfung warnt, wenn sie bei dem Einführer fehlt, der die Batterie in Verkehr bringt. Wird im öffentlichen Pass angezeigt.

    e.g. EuroBat

  • postalAddress

    string (max 500 chars)

    Postanschrift mit einer zentralen Kontaktstelle, in einer Zeile. Wird im öffentlichen Pass angezeigt.

    e.g. Industriestraße 42, 80339 Munich, Germany

  • email

    string (email)

    Kontakt-E-Mail-Adresse. Wird im öffentlichen Pass angezeigt, verwenden Sie daher eine Firmenadresse, keine persönliche.

    e.g. compliance@example.com

  • 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