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>`). Tutti e cinque gli schemi EN 18219 si risolvono nello stesso viewer pubblico. 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}/registry-upiOttenere l'indirizzo EU DPP Registry di un passaporto della batteria
Restituisce l'identificatore unico del prodotto (UPI) da incollare nel modulo online dell'EU DPP Registry per un passaporto della **batteria** pubblicato, come `{ upi, preparedAt }`. L'operatore economico registra il passaporto sul sito web del registro con il proprio EU Login (Product group: Batteries; Granularity: Item). TracePass prepara l'indirizzo e annota di averlo fatto; non presenta mai nulla al registro.
/api/v1/registry/upload-fileCreare il file di caricamento per l'EU DPP Registry
Crea il file XML che l'operatore economico carica sul sito web dell'EU DPP Registry (DPP Registration → upload a file) per i passaporti della **batteria** che indicate, fino a 100 per chiamata. La registrazione è un atto proprio dell'operatore con il proprio EU Login; TracePass prepara il file e non lo presenta mai.
/api/v1/passports/{id}/registrationAnnotare l'esito dell'EU DPP Registry per un passaporto della batteria
Annota ciò che l'operatore economico riporta dal sito web dell'EU DPP Registry per un passaporto della **batteria** pubblicato. TracePass annota la dichiarazione dell'operatore e non la verifica presso il registro. Il corpo ha una di due forme, scelta tramite `environment`.
/api/v1/passports/{id}/registrationAnnullare un esito dell'EU DPP Registry annotato per errore
Cancella un esito annotato con `POST /api/v1/passports/{id}/registration`; il parametro di query obbligatorio `environment` indica quale. Non cambia nulla nell'EU DPP Registry stesso: corregge ciò che TracePass conserva per il passaporto. L'annullamento viene registrato.
/api/v1/passports/{id}/place-on-marketInviare un passaporto della batteria all'API di un registro EN 18222
Invia un passaporto della **batteria** pubblicato a un registro che accetta la chiamata `registerDPP` della EN 18222, con l'accesso all'API del registro configurato per il vostro account (una chiave API o un bearer token), quindi la registrazione avviene con le vostre credenziali. Solo passaporti di batterie.
/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, a meno che il passaporto non sia stato reindirizzato a un nuovo fornitore. 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}/mark-for-deletionContrassegnare un passaporto per l'eliminazione
**Primo di due passaggi.** Un passaporto si elimina in due passaggi: lo contrassegnate qui per l'eliminazione, poi chiamate `DELETE /api/v1/passports/{id}` (un passaporto mai pubblicato in stato `draft` o `in_review` si può eliminare direttamente). L'eliminazione è logica (soft delete): nulla viene cancellato, ma il passaporto scompare dall'API e da ogni superficie pubblica. Chi scansiona il codice QR vede una pagina che indica che il passaporto è terminato, e i formati leggibili da macchina rispondono `410 Gone`.
/api/v1/passports/{id}Eliminare un passaporto
**Un passaporto contrassegnato per l'eliminazione → eliminazione logica.** Un passaporto che è stato pubblicato si elimina in due passaggi: prima `POST /api/v1/passports/{id}/mark-for-deletion`, poi questo DELETE. Nulla viene cancellato: il passaporto scompare dall'API (da quel momento ogni chiamata v1 su di esso restituisce `404`) e da ogni superficie pubblica. Chi scansiona il codice QR vede una pagina che indica che il passaporto è terminato, e i formati leggibili da macchina rispondono `410 Gone`. Restituisce il passaporto con `status: "deleted"` e attiva il webhook `passport.deleted`.
/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? }`). 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, dalla più recente ricevuta (per `receivedAt`). 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`.
/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`.