Passaporti
Create, aggiornate, sospendete, archiviate e importate in massa passaporti digitali di prodotto. Include il blocco parties per le catene di operatori economici.
/api/v1/passportsCreare un passaporto
Crea un singolo passaporto digitale di prodotto. Il passaporto è vincolato a un prodotto (productId) e identificato da un GS1 GTIN + un numero di serie univoco all'interno di quel GTIN. I nuovi passaporti iniziano nello stato `draft` — i campi vengono popolati tramite successive chiamate PATCH e il passaporto viene pubblicato dalla dashboard una volta completata la revisione.
/api/v1/passports/{id}Leggere un singolo passaporto
Legge un passaporto per ID. La risposta predefinita include il passaporto completo — i campi traducibili portano il loro `sourceLocale` e una mappa `translations` per locale. Passate `?lang=<locale>` per far risolvere al server ogni campo attraverso la catena del visualizzatore pubblico (traduzione nel locale del visualizzatore → valore del locale di origine → inglese → primo applicato → fonte universale) e restituire un valore risolto per campo; la mappa `translations` viene rimossa dalle risposte risolte per lang.
/api/v1/passports/{id}/qrRenderizzare il QR del passaporto
Restituisce un codice QR appena renderizzato per il passaporto, che codifica il suo URI identificatore effettivo. Per i passaporti GS1 è il GS1 Digital Link URI (`/01/<gtin>/21/<serial>`); per ISO 15459 è il percorso del resolver; per i passaporti iec61406, did e doi è il percorso resolver `/x/<scheme>/<encodedValue>` (es. `https://id.tracepass.eu/x/did/<encodedDid>`). L'host del resolver riscrive `/x/*` in `/p/x/*` così lo stesso viewer serve tutti e cinque gli schemi EN 18219. Usatelo quando volete il nostro renderer (quiet zone coerente, correzione d'errore, branding facoltativo) invece di codificare voi l'URI. Il default è `image/svg+xml`; `?format=png` restituisce un PNG e `?format=json` un wrapper `{ result: "<svg>" }` da incorporare.
/api/v1/passports/{id}/complianceVerificare la conformità del passaporto
Restituisce un verdetto di conformità a tre livelli per un passaporto — `compliant`, `compliant_with_warnings` o `incomplete` — insieme a findings che citano il regolamento, così un'integrazione può verificare le lacune di un passaporto, correggere le lacune indicate e richiamare per confermare. Quella catena leggere → correggere → verificare è lo scopo: la risposta indica all'agente IA esattamente cosa impostare in seguito.
/api/v1/passports/{id}/registry-readinessVerificare la prontezza per il registro
Restituisce se un passaporto supererebbe il **gate formale di invio dell'EU DPP Registry** — `{ ready, findings[] }`. È il controllo *meccanico* del registro prima dell'invio, distinto da e complementare al verdetto sostanziale `/compliance`: un passaporto può essere pronto per il registro senza essere sostanzialmente conforme, e viceversa. Chiamalo prima dell'invio al registro per individuare presto le lacune formali.
/api/v1/passportsElencare i passaporti
Elenco paginato dei passaporti posseduti dallo spazio di lavoro. Filtrate per `productId`, `status`, oppure con una ricerca a testo libero su GTIN e numero di serie. Viene conteggiato sul budget giornaliero di lettura passaporti (`maxV1PassportsPerDay`); gli elementi della risposta usano la stessa forma dell'endpoint di lettura singola ma ridotta ai campi dell'elenco.
/api/v1/passports/{id}/fields/{key}Aggiornare un campo su un passaporto
Applica una patch a un singolo campo su un passaporto. Il valore viene convalidato rispetto alla chiave del campo (deve esistere nel template del passaporto) e persistito con una voce di traccia di controllo che indica la credenziale (`via API key <prefix>` o `via OAuth app <client>`) e, quando l'header `X-Source` è impostato, il client chiamante, ad es. `(mcp)`. Preferite questo alla scrittura dell'intera mappa `fields` quando dovete aggiornare un solo numero — è una scrittura più piccola e la voce di controllo per campo è ciò che vedono i revisori della dashboard.
/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.
/api/v1/passports/{id}/suspendSospendere un passaporto
Sospensione reversibile. Il visualizzatore pubblico passa alla pagina di stato sospeso (HTTP 423 con corpo strutturato); le scansioni QR di fatto smettono di funzionare senza che l'URL vada in 404. Usatelo per richiami, controversie, blocchi interni o indagini sulla qualità del prodotto. Ripubblicate dalla dashboard una volta risolto.
/api/v1/passports/{id}/archiveArchiviare un passaporto (irreversibile)
**Irreversibile.** Il visualizzatore pubblico restituisce 404, l'URL GS1 Digital Link smette di risolvere, il codice QR muore definitivamente. Usatelo SOLO per prodotti mai spediti — archiviare il passaporto di un prodotto già nelle mani dei clienti rompe ogni scansione QR che ne faranno.
/api/v1/passports/{id}Eliminare un passaporto definitivamente
**Permanente e irreversibile** — la riga del passaporto più ogni dipendenza in cascata vengono rimosse dal database. La cascata include estrazioni IA, stato della sessione dell'agente, richieste ai fornitori collegate solo a questo passaporto, eventi di scansione + assistenza, e qualsiasi documento caricato la cui unica referenza era questo passaporto (i documenti condivisi con altri passaporti/prodotti restano). Anche lo storage R2 sotto la cartella del passaporto viene ripulito.
/api/v1/passports/batchCreazione massiva di passaporti
Create fino a 100 passaporti in una sola chiamata. Ogni elemento porta la stessa forma del corpo dell'endpoint di creazione singola (`{ productId, gs1: { gtin, serialNumber }, parties?, confirmOverage? }`). Successo parziale per elemento — ognuno ottiene il proprio stato nell'array di risposta.
/api/v1/passports/{id}/snapshotsElencare gli snapshot del passaporto
Restituisce un elenco paginato di **snapshot** di immutabilità per un passaporto, dal più recente. Uno snapshot viene scritto alla pubblicazione e dopo ogni modifica di un passaporto pubblicato, sospeso, scaduto o archiviato — valori dei campi, traduzioni, parti, cambi di stato, risposte dei fornitori, scritture dell'IA, ripristini — quando il contenuto del passaporto è effettivamente cambiato (EN 18221:2026, 4.2). Ogni voce include l'id dello snapshot, il numero di versione, il motivo (ad es. `published`, `field_edit`, `status_change`, `baseline`), chi ha causato la modifica (`actor`, se noto), il timestamp, l'hash del contenuto e se l'hash ancora verifica — `hashValid: false` indica una manomissione at-rest.
/api/v1/passports/{id}/snapshots/{snapshotId}Ottenere uno snapshot del passaporto
Restituisce il registro archivistico completo per uno **snapshot** di immutabilità: l'intero payload JSON-LD esattamente com'era il passaporto quando è stato acquisito lo snapshot — alla pubblicazione o dopo ogni modifica di un passaporto pubblicato, sospeso, scaduto o archiviato — i metadati dello snapshot (versione, motivo, `actor` — chi ha causato la modifica — e timestamp) e la ri-verifica dell'hash del contenuto. Per ottenere la versione valida a una certa data, usare `?at=` in **Elencare gli snapshot del passaporto**. `hashValid: false` significa che il payload memorizzato è stato modificato dopo che lo snapshot è stato acquisito — indicativo di manomissione at-rest.
/api/v1/passports/{id}/condition-flagsLeggere i flag di classificazione condizionale
Restituisce il **condition profile** risolto per un passaporto — `Record<flagKey, { value, status, source }>`. I condition flag sono fatti sì/no approvati da un revisore su un prodotto che attivano obblighi legali condizionali. Per i passaporti delle batterie ai sensi del Regolamento (UE) 2023/1542, i flag registrati sono: `hasBMS` (sistema di gestione della batteria presente), `rechargeable` (la batteria è ricaricabile), `externalStorageOnly` (si applica l'esenzione art. 8), e `isStationaryBess` (sistema stazionario di accumulo di energia a batteria). Le categorie senza flag registrati restituiscono un profilo vuoto.
/api/v1/passports/{id}/condition-flagsImpostare i flag di classificazione condizionale
Scrive uno o più condition flag su un passaporto. Il corpo della richiesta è `Record<flagKey, boolean | null>` — `true` o `false` imposta il flag; `null` lo cancella. Vengono accettate solo le chiavi registrate per la categoria del passaporto; chiavi sconosciute restituiscono 400 con le chiavi valide per quella categoria.
/api/v1/passports/{id}/measurementsAcquisire misurazioni
**Solo per passaporti della batteria** (Regolamento (UE) 2023/1542 Art. 77, Allegato XIII punto 4 — dati d'uso). Il passaporto deve essere pubblicato; una bozza o un passaporto sospeso restituisce 422 `passport_not_active`. Un passaporto non relativo a una batteria restituisce 422 `not_a_battery`. Inviare da 1 a 500 misurazioni per chiamata, ciascuna come `{ fieldKey, value, measuredAt, externalId?, unit? }` — `measuredAt` è un timestamp ISO 8601, non può essere nel futuro; `value` deve essere al massimo **16 KB una volta serializzato** (un valore più grande restituisce 400 `invalid_value`). Le `fieldKey` accettate sono i campi dati d'uso dell'Allegato XIII punto 4: `stateOfHealth`, `stateOfCertifiedEnergy`, `remainingCapacity`, `remainingPowerCapability`, `remainingRoundTripEfficiency`, `evolutionOfSelfDischargeRate`, `currentInternalResistancePack`, `capacityFade`, `powerFade`, `internalResistanceIncrease`, `dynamicRatedCapacity`, `dynamicPowerCapability`, `dynamicInternalResistance`, `dynamicEnergyRoundTripEfficiency`, `dynamicExpectedLifetimeCycles`, `numberOfFullEquivalentChargingCycles`, `numberOfChargingEvents`, `currentStateOfCharge`, `negativeEvents`, `temperatureConditionsHistorical`.
/api/v1/passports/{id}/measurementsCronologia delle misurazioni
Restituisce la cronologia completa delle misurazioni per un passaporto della batteria, dalla più recente (per `measuredAt`). Ogni voce è un oggetto `PassportMeasurement` con `_id`, `passportId`, `fieldKey`, `value`, `measuredAt`, `receivedAt`, `externalId?`, `unit?`, `materialized` (se questa voce è diventata il valore corrente del campo nel passaporto) e `source`. **Solo passaporti della batteria** — un passaporto non relativo a una batteria restituisce 422 `not_a_battery`.
/api/v1/passports/{id}/measurements/latestUltime misurazioni
Restituisce la misurazione più recente per ciascuno dei campi dati d'uso accettati dell'Allegato XIII punto 4. La risposta è `{ data: { <fieldKey>: LatestMeasurement | null } }` — tutte le chiavi accettate sono sempre presenti; una chiave è `null` quando non è ancora stata ricevuta alcuna misurazione per quel campo. Una `LatestMeasurement` contiene `value`, `measuredAt` e facoltativamente `unit` e `externalId`. **Solo passaporti della batteria** — un passaporto non relativo a una batteria restituisce 422 `not_a_battery`.