TracePass
Inizia ora
Passaporti

Upsert di una parte operatore economico

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.

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

Upsert di una parte operatore economico

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.

Almeno uno tra `gln`, `legacyOperatorId` o `operatorIdentifier` deve essere impostato — senza un identificatore la Party non identifica effettivamente nessuno. `operatorIdentifier` porta un identificatore strutturato con tag di schema per EN 18219 §6.2–6.5 (iso6523, gln, did, doi). Quando lo schema è `gln`, riempie anche il campo `gln` di livello superiore; se entrambi sono impostati devono corrispondere (400 con percorso `operatorIdentifier`). `facilityIdentifier` utilizza gli stessi schemi e identifica il luogo in cui opera l'operatore — non riempie mai `gln`. Gli identificatori tipizzati non sono impostati dall'estrazione AI o dall'importazione CSV.

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.

Parametri di percorso

  • idobbligatorio

    ObjectId

    ID del passaporto.

    e.g. 6650b2c3d4e5f6a7b8c9d0e1

  • roleobbligatorio

    enum

    Uno tra: `manufacturer`, `importer`, `authorisedRepresentative`, `distributor`, `recycler`, `producerResponsibilityOrg`. I ruoli al di fuori di questo elenco restituiscono 400.

    e.g. recycler

Header

  • Authorizationobbligatorio

    string

    `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.

    e.g. Bearer tp_REDACTED_xxxxxxxxxxxx

  • Idempotency-Key

    string

    UUID v4 per operazione logica.

Campi del corpo

  • legalNameobbligatorio

    string (1-200 chars)

    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.

    e.g. EuroBat Recyclers GmbH

  • gln

    string (13 digits)

    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.

    e.g. 4012345678901

  • country

    string (ISO 3166-1 alpha-2)

    Codice paese di due lettere maiuscole — es. `DE`, `BG`, `FR`.

    e.g. DE

  • legacyOperatorId

    string (1-120 chars)

    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.

    e.g. DE123456789

  • url

    string (URL, max 500 chars)

    Pagina dell'organizzazione — tipicamente il sito web aziendale o una sottopagina con informazioni societarie.

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

  • operatorIdentifier

    object (EN 18219 §6.2–6.5)

    Identificatore strutturato dell'operatore per EN 18219 §6.2–6.5. Richiede `scheme` più campi specifici dello schema. Schemi: `iso6523` — ICD (codice ISO/IEC 6523 a 4 cifre, es. 0199 = LEI, 0088 = GLN, 0060 = DUNS) + `value`; `gln` — GLN a 13 cifre (riempie anche il campo `gln` di livello superiore; devono corrispondere se entrambi impostati); `did` — URI DID in forma `did:<metodo>:<id>` (solo controllo sintattico, EN 18219 §6.4.2(b)); `doi` — DOI in forma `10.<registrant>/<suffisso>` (prefisso `doi:` / `https://doi.org/` accettato e rimosso). Non impostato da estrazione AI o importazione CSV.

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

  • facilityIdentifier

    object (EN 18219 §6.2–6.5)

    Identificatore strutturato della struttura per EN 18219 §6.2–6.5 — identifica dove opera l'operatore, non l'operatore stesso. Usa gli stessi quattro schemi di `operatorIdentifier`; la variante `gln` accetta anche `extension` (codice di sotto-localizzazione GS1 SGLN). Non riempie mai il campo `gln` di livello superiore. Non impostato da estrazione AI o importazione CSV.

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

Richiesta

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

Risposta

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

Endpoint correlati