---
title: Wirtschaftsakteurs-Partei upsert
description: Eine Wirtschaftsakteurs-Partei am Pass setzen oder ersetzen (Hersteller, Importeur, Händler, Bevollmächtigter). GLN validiert. Audit-Eintrag.
canonical: "https://www.tracepass.eu/de/docs/upsert-party"
locale: de
source: "https://www.tracepass.eu/de/docs/upsert-party"
---

# Wirtschaftsakteurs-Partei upsert

> Eine Wirtschaftsakteurs-Partei am Pass setzen oder ersetzen (Hersteller, Importeur, Händler, Bevollmächtigter). GLN validiert. Audit-Eintrag.

```http
PATCH /api/v1/passports/{id}/parties/{role}
```

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.

Die Identität wird vollständig durch den Body ausgedrückt: `legalName` (erforderlich), `gln` (GS1 Global Location Number — dringend empfohlen für Mehrrollen-Disambiguierung), `country` (ISO 3166-1 alpha-2), `legacyOperatorId` (USt-ID / EORI / Lieferantencode als Free-Text-Fallback), `url`. Mindestens eines von `gln` oder `legacyOperatorId` muss gesetzt sein — ohne Identifier identifiziert die Party niemanden. Wenn zwei Rollen dieselbe `gln` teilen, fasst die JSON-LD-Emission sie zu einer Partei mit mehreren Rollen zusammen.

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.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Authorization` | header | string | yes | `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. |
| `Idempotency-Key` | header | string | no | UUID v4 pro logischer Operation. |
| `id` | path | ObjectId | yes | Pass-ID. |
| `role` | path | enum | yes | Einer von: `manufacturer`, `importer`, `authorisedRepresentative`, `distributor`, `recycler`, `producerResponsibilityOrg`. Andere Rollen liefern 400 zurück. |
| `legalName` | body | string (1-200 chars) | yes | Name der juristischen Person wie im Handelsregister. Erforderlich — eine Party ohne Namen hilft keinem Procurement-Leser, unabhängig vom getragenen Identifier. |
| `gln` | body | string (13 digits) | no | 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. |
| `country` | body | string (ISO 3166-1 alpha-2) | no | Zweibuchstabiger Großbuchstaben-Ländercode — z. B. `DE`, `BG`, `FR`. |
| `legacyOperatorId` | body | string (1-120 chars) | no | Free-Text-Fallback-Identifier für Parteien ohne GLN — USt-IdNr., EORI, Lieferantencode oder eine interne ID Ihres ERP. Erforderlich, wenn `gln` ausgelassen wird. |
| `url` | body | string (URL, max 500 chars) | no | Organisationsseite — typischerweise die Unternehmenswebsite oder eine Corporate-Info-Unterseite. |

## Examples

```bash
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"
  }'
```

```typescript
await fetch(
  `https://app.tracepass.eu/api/v1/passports/${id}/parties/recycler`,
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.TRACEPASS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      legalName: "EuroBat Recyclers GmbH",
      gln: "4012345678901",
      country: "DE",
      url: "https://eurobat-recyclers.example",
    }),
  },
);
```

```python
import os, requests
res = requests.patch(
    f"https://app.tracepass.eu/api/v1/passports/{passport_id}/parties/recycler",
    headers={"Authorization": f"Bearer {os.environ['TRACEPASS_API_KEY']}"},
    json={
        "legalName": "EuroBat Recyclers GmbH",
        "gln": "4012345678901",
        "country": "DE",
        "url": "https://eurobat-recyclers.example",
    },
)
res.raise_for_status()
```

## Responses

### 200 — Upserted

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

### 400 — Validierungsfehler

```json
{
  "error": "Validation error",
  "details": {
    "fieldErrors": {
      "gln": ["Party must have at least one identifier (gln or legacyOperatorId)"]
    }
  }
}
```

### 404 — Nicht gefunden

```json
{ "error": "Passport not found" }
```

## Related

- [Pass anlegen (Parties beim Erstellen)](https://www.tracepass.eu/de/docs/create-passport.md)
- [Einzelnes Feld aktualisieren](https://www.tracepass.eu/de/docs/update-field.md)