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.

Un LEI (iso6523 con ICD 0199) viene verificato nel registro GLEIF. Se GLEIF non lo conosce o lo segnala come ANNULLED o DUPLICATE, la risposta è 400 (per un duplicato il messaggio indica il LEI da usare). Un LEI LAPSED, RETIRED o di un'entità inattiva, oppure un legalName che non corrisponde a nessuno dei nomi registrati in GLEIF per quel LEI, viene salvato e segnalato in un array warnings nella risposta.

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.

Una volta immesso sul mercato un passaporto batteria, una scrittura che cambierebbe un operatorIdentifier o un facilityIdentifier memorizzato risponde 409 operator_locked (keys indica <role>.<field>); le altre modifiche alle parti restano consentite. Per correggere un identificativo bloccato, contrassegnate il passaporto per l'eliminazione e createne uno nuovo.

Parametri di percorso

  • idobbligatorio

    string (24 hex chars)

    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

  • tradeName

    string (max 200 chars)

    Denominazione commerciale registrata o marchio registrato. Per un importatore di batterie è uno dei dati che indica sulla batteria (regolamento batterie, art. 41, paragrafo 3); il controllo di conformità avvisa quando manca per l'importatore che immette la batteria sul mercato. Mostrato nel passaporto pubblico.

    e.g. EuroBat

  • postalAddress

    string (max 500 chars)

    Indirizzo postale con un unico punto di contatto, su una riga. Mostrato nel passaporto pubblico.

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

  • email

    string (email)

    Indirizzo di posta elettronica di contatto. Mostrato nel passaporto pubblico, quindi usate un indirizzo aziendale, non personale.

    e.g. compliance@example.com

  • 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