---
title: Upsert di una parte operatore economico
description: Imposta o sostituisce una parte operatore economico (fabbricante, importatore, distributore, mandatario). GLN validato. Voce di audit.
canonical: "https://www.tracepass.eu/it/docs/upsert-party"
locale: it
source: "https://www.tracepass.eu/it/docs/upsert-party"
---

# Upsert di una parte operatore economico

> Imposta o sostituisce una parte operatore economico (fabbricante, importatore, distributore, mandatario). GLN validato. Voce di audit.

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

Crea o sostituisce la Party per un singolo ruolo su un passaporto. Il segmento di percorso role determina lo slot in cui state scrivendo — `manufacturer`, `importer`, `authorisedRepresentative`, `distributor`, `recycler`, `producerResponsibilityOrg`. Inviare due volte lo stesso ruolo è un upsert: il blocco esistente viene sostituito in modo atomico.

L'identità è espressa completamente dal corpo: `legalName` (obbligatorio), `gln` (GS1 Global Location Number — fortemente consigliato per la disambiguazione tra più ruoli), `country` (ISO 3166-1 alpha-2), `legacyOperatorId` (partita IVA / EORI / codice fornitore come fallback a testo libero), `url`. Almeno uno tra `gln` o `legacyOperatorId` deve essere impostato — senza un identificatore la Party non identifica effettivamente nessuno. Quando due ruoli condividono lo stesso `gln`, l'emissione JSON-LD li unisce in un'unica parte con più ruoli.

Conta come una scrittura v1. Rispetta `Idempotency-Key`. Il Regolamento sulle batterie richiede almeno { manufacturer, importer (se applicabile), recycler } prima che un passaporto venga accettato; la scheda di completezza normativa della piattaforma evidenzia i ruoli mancanti nella dashboard. Il corrispondente `DELETE /api/v1/passports/{id}/parties/{role}` rimuove un ruolo in modo idempotente.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Authorization` | header | string | yes | `Bearer <token>` — una chiave API `tp_` (Developer → API Keys; più semplice, per server-to-server) oppure un access token OAuth 2.0 (Developer → OAuth Apps; per app autorizzate dall'utente, scoped e revocabili). La pagina Authentication contiene il flusso OAuth completo e l'elenco degli scopes. |
| `Idempotency-Key` | header | string | no | UUID v4 per operazione logica. |
| `id` | path | ObjectId | yes | ID del passaporto. |
| `role` | path | enum | yes | Uno tra: `manufacturer`, `importer`, `authorisedRepresentative`, `distributor`, `recycler`, `producerResponsibilityOrg`. I ruoli al di fuori di questo elenco restituiscono 400. |
| `legalName` | body | string (1-200 chars) | yes | Nome della persona giuridica come compare nel registro delle imprese. Obbligatorio — una Party senza nome non aiuta nessun lettore degli acquisti, indipendentemente dall'identificatore che porta. |
| `gln` | body | string (13 digits) | no | GS1 Global Location Number con cifra di controllo mod-10 valida. Fortemente consigliato — quando due ruoli condividono lo stesso `gln`, il JSON-LD emette un'unica parte con entrambi i ruoli associati. Deve essere convalidato come un GLN reale; stringhe parziali / solo cifre restituiscono 400. |
| `country` | body | string (ISO 3166-1 alpha-2) | no | Codice paese di due lettere maiuscole — es. `DE`, `BG`, `FR`. |
| `legacyOperatorId` | body | string (1-120 chars) | no | Identificatore di fallback a testo libero per le parti che non hanno un GLN — partita IVA, EORI, codice fornitore o qualsiasi ID interno che il vostro ERP porta. Obbligatorio quando `gln` è omesso. |
| `url` | body | string (URL, max 500 chars) | no | Pagina dell'organizzazione — tipicamente il sito web aziendale o una sottopagina con informazioni societarie. |

## 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 — Upsert eseguito

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

### 400 — Errore di convalida

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

### 404 — Non trovato

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

## Related

- [Creare un passaporto (parti al momento della creazione)](https://www.tracepass.eu/it/docs/create-passport.md)
- [Aggiornare un campo su un passaporto](https://www.tracepass.eu/it/docs/update-field.md)