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.

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.

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

    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

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