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 `gs1.digitalLinkUri`. 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/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 contrassegnata `via API key <prefix>`. 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.