API del registro DPP: come registrare i passaporti delle batterie presso l'UE, passo dopo passo

TL;DR

• Il 30 ottobre 2026 la Commissione europea ha pubblicato le specifiche tecniche dell'API del registro DPP: una guida all'integrazione, i file OpenAPI, le guide all'autenticazione per gli account di servizio e per i passaporti ospitati in proprio, e i modelli di dati semantici per le batterie.
• La registrazione è asincrona e «tutto o niente»: invii fino a 100 passaporti per richiesta, il registro recupera e convalida ciascun passaporto dal suo indirizzo web e, se un solo elemento non supera i controlli, nessuno viene registrato.
• Le batterie sono finora l'unico gruppo di prodotti definito. Le batterie per veicoli elettrici, quelle LMT e quelle industriali superiori a 2 kWh devono avere un passaporto registrato dal 18 febbraio 2027, e la tua organizzazione deve essere verificata con un sigillo elettronico qualificato prima che qualsiasi chiamata API funzioni.

L'API del registro DPP è il modo in cui un fabbricante, un importatore o la piattaforma che lavora per loro registra i passaporti digitali di prodotto presso l'UE senza compilare un modulo web un prodotto alla volta. Il registro in sé è operativo dal 20 luglio 2026. Ciò che è arrivato il 30 ottobre è il dettaglio che serve a uno sviluppatore per integrarsi: endpoint, autenticazione, codici di errore, regole di polling e i modelli di dati rispetto ai quali il registro convalida i passaporti.

Questa guida è per chi deve far comparire i passaporti delle batterie nel registro entro febbraio. Segue i documenti nell'ordine in cui li incontrerai e separa ciò che è deciso da ciò che è ancora aperto. Per sapere cos'è il registro e perché esiste, consulta la nostra guida al registro DPP dell'UE. Tutto quanto segue è aggiornato a novembre 2026.

Che cosa ha pubblicato la Commissione il 30 ottobre?

Sei documenti tecnici sono comparsi sulla pagina delle risorse DPP della Commissione, senza una notizia ad annunciarli. Si affiancano alla User Guide for Economic Operators di settembre 2026.

Il 19 ottobre la Commissione ha inoltre pubblicato la versione 3.2 delle sue linee guida sul passaporto della batteria, che elenca i dati per categoria di batteria. Ne parliamo più avanti.

La parte vincolante è il regolamento di esecuzione (UE) 2026/1778 del 16 luglio 2026. L'articolo 3, lettera b), prevede un'API per la registrazione, l'articolo 8, paragrafo 6, consente la registrazione tramite l'interfaccia utente o l'API, e l'articolo 8, paragrafo 7, impone controlli automatici della semantica e della granularità. Le specifiche sono il modo in cui la Commissione attua quegli articoli.

Che cosa fa il registro con il tuo passaporto?

Il registro è un indice, non un archivio. Gli invii un identificativo univoco del prodotto (UPI) per ogni passaporto, e l'API richiede che quell'UPI sia un URL HTTPS. Al momento dell'invio, il registro va a quell'URL, recupera il passaporto e lo convalida rispetto al modello di dati del gruppo di prodotti. Nelle parole della guida all'integrazione, il registro «non conserva in modo persistente il contenuto del payload DPP recuperato».

Questa sola scelta progettuale determina gran parte del lavoro di ingegneria. Il passaporto deve essere online, completo e valido nel momento in cui lo invii, non dopo. Se il registro non riesce a raggiungerlo, l'elemento fallisce con UPI_NOT_RESOLVABLE. Se il contenuto non corrisponde allo schema, fallisce come ITEM_NON_COMPLIANT. Un flusso che prima registra e poi pubblica il passaporto non funzionerà.

Una volta riuscita la registrazione, l'articolo 9 del regolamento di esecuzione ti fornisce una prova di registrazione sigillata con il sigillo elettronico qualificato della Commissione, disponibile per 90 giorni. Scaricala e archiviala: è la tua prova che il passaporto è stato registrato, e di quando.

Che cosa deve essere pronto prima della prima chiamata API?

Più di quanto la maggior parte dei team si aspetti, e quasi nulla di tutto ciò è codice.

Un'organizzazione verificata. Gli utenti accedono con EU Login, ma l'API rifiuta con un 403 le richieste di un'organizzazione non verificata. Ai sensi dell'articolo 4 del regolamento di esecuzione, una persona giuridica dimostra la propria identità e il proprio stabilimento con un sigillo elettronico qualificato (o con un attestato elettronico di attributi); un'impresa individuale può usare una firma elettronica qualificata o un'eID con livello di garanzia eIDAS «elevato». In pratica, il registro ti fornisce una dichiarazione sigillata dalla Commissione, e tu la firmi o la sigilli. Lo stato di verifica dura fino alla scadenza dei tuoi mezzi di identificazione, e non oltre tre anni, dopodiché devi verificarti di nuovo.

Un sigillo qualificato viene rilasciato da un prestatore di servizi fiduciari qualificato, con i propri controlli di identità. Se la tua azienda non ne possiede uno, inizia da qui.

Un amministratore e un account di servizio. L'amministratore della tua organizzazione crea gli account di servizio nell'interfaccia del registro. Un account di servizio è un'identità non umana legata alla tua organizzazione verificata, e ha bisogno del ruolo che consente di registrare i DPP. L'organizzazione viene ricavata dal token di accesso, quindi non passi mai un ID di organizzazione nella richiesta.

Classificazione del prodotto. Ogni invio indica un gruppo e un sottogruppo di prodotti, che ricavi da GET /api/v1/dpp/product-groups anziché codificarli a mano. Oggi quella chiamata restituisce un solo gruppo, BATTERIES, con i sottogruppi EV, LMT e industriali.

Come si autentica un account di servizio?

Il registro usa le credenziali client OAuth 2.0 con private_key_jwt. La guida è netta: «I client secret condivisi non sono supportati.» Il tuo sistema conserva una chiave privata, firma un'asserzione di breve durata e la scambia con un token di accesso.

I dettagli che coglieranno in fallo molti:

• Solo chiavi a curva ellittica (ES256, ES384 o ES512). Le chiavi RSA non sono accettate. Carichi la chiave pubblica come JWK o PEM, e la guida raccomanda di conservare la chiave privata in un modulo di sicurezza hardware.
• Asserzioni brevi. L'asserzione client dovrebbe scadere tra 60 e 120 secondi, mai oltre 5 minuti, con un jti nuovo ogni volta.
• Un indicatore di risorsa. La richiesta di token deve indicare il registro come risorsa, usando il valore pubblicato per ciascun ambiente.
• Token brevi. I token di accesso durano al massimo 15 minuti, quindi il tuo client deve rinnovarli durante le esecuzioni di batch lunghe.
• Limiti. Fino a 5 account di servizio per organizzazione e 2 credenziali attive per account, ed è questo che rende possibile la rotazione delle chiavi senza interruzioni. Si raccomanda che le credenziali durino un anno, al massimo due.

Se una piattaforma registra i passaporti per tuo conto, il modello descritto dai documenti della versione 1.0 è un account di servizio all'interno della tua organizzazione verificata. È così che funziona l'integrazione oggi, ma non è l'unica via consentita dalla legge. Il regolamento di esecuzione prevede anche terzi verificati che agiscono per conto di un operatore: l'articolo 6, paragrafo 1, consente agli operatori verificati di delegare diritti di accesso a terzi laddove il diritto dell'Unione lo preveda, l'articolo 8, paragrafo 2, consente in tal caso a un terzo verificato di eseguire azioni di registrazione, e l'articolo 19, paragrafo 4, impone a un terzo autorizzato da un operatore di sottoporsi a una propria verifica. Il registro terrà inoltre un elenco dei fornitori di servizi DPP verificati (articolo 3, lettera f)). Come funzionerà tecnicamente tale delega non è ancora descritto nelle guide all'integrazione. Qualunque sia la via utilizzata, l'operatore economico resta pienamente responsabile della conformità.

Come funziona un invio di registrazione?

Il flusso prevede quattro chiamate. Recuperi i gruppi di prodotti, invii, poi monitori l'attività tramite quella che la Commissione chiama Activity Dashboard API.

POST /api/v1/dpp/submission
Authorization: Bearer <access token>
Idempotency-Key: 7f3c9a2e-batch-2027-02-01-001
Content-Type: application/json

{
  "productGroup": "BATTERIES",
  "productSubGroup": "EV",
  "submissionItems": [
    {
      "uniqueProductIdentifier": "https://example.com/dpp/battery/0001",
      "granularity": "item",
      "batchIdentifier": "xxx-000",
      "modelIdentifier": "yyy-111"
    }
  ]
}

Questo corpo segue l'esempio ufficiale. uniqueProductIdentifier e granularity (articolo, lotto o modello) sono obbligatori per ogni elemento; gli identificativi di lotto e di modello sono facoltativi.

Il registro risponde 202 Accepted con un taskId. Un 202 significa soltanto che la richiesta è stata accettata per l'elaborazione. Poi interroghi GET /api/v1/tasks/{taskId} e, quando ti serve sapere quali elementi sono stati accettati, GET /api/v1/tasks/{taskId}/items, che restituisce JSON o CSV.

Contano due campi di stato, e significano cose diverse. Lo status dell'attività passa per PENDING, PROCESSING, COMPLETED o ERROR. Una volta completata, outcomeResult indica SUCCEEDED o FAILED. Un'attività può essere COMPLETED con esito FAILED: l'elaborazione ha funzionato, ma i tuoi dati non hanno superato i controlli. ERROR è un guasto tecnico lato registro.

Non ci sono webhook. La guida raccomanda di interrogare a 1, 1, 2, 3, 5, 8, 13, 21, 34 e 55 secondi, poi al massimo ogni 60 secondi, e un'intestazione Retry-After prevale sempre sulla tua pianificazione.

La regola che dovrebbe guidare la progettazione dei batch è l'atomicità. Un invio contiene da 1 a 100 passaporti dello stesso gruppo e sottogruppo di prodotti e, se anche uno solo non è conforme, nessuno viene registrato, compresi quelli che hanno superato i controlli. Un record errato in un batch da 100 blocca 99 record validi. Noi convalideremmo ogni passaporto in locale rispetto agli schemi pubblicati prima dell'invio, terremmo i batch più piccoli finché i dati non si sono stabilizzati e reinvieremmo rapidamente gli elementi corretti dopo un fallimento.

L'intestazione Idempotency-Key è obbligatoria, fino a 128 caratteri. Riprovare con la stessa chiave restituisce l'attività originale anziché crearne un duplicato, ed è ciò che vuoi dopo un timeout o un 500. Un invio modificato richiede una nuova chiave; riutilizzare una chiave per contenuti diversi restituisce un 409.

I codici di errore sono quelli convenzionali (400, 403, 409, 413, 422, 429, 500), e per ciascuno la guida indica se riprovare con la stessa chiave o con una nuova. Un 403 di solito significa che l'organizzazione non è verificata o che l'account di servizio non ha il ruolo di registrazione.

Che cosa cambia se ospiti i passaporti in proprio?

I passaporti delle batterie contengono dati pubblici e riservati, e il registro li legge entrambi durante la convalida. Se il passaporto si trova sul tuo server, quel server deve riconoscere il registro e mostrargli più di quanto mostra al pubblico.

Il tuo host dei passaporti funge da resource server OAuth 2.0. Il registro richiede prima l'UPI senza credenziali e si aspetta il passaporto pubblico. Poi richiede lo stesso URL con un bearer token emesso dal servizio di autenticazione della Commissione, e si aspetta i dati pubblici più quelli riservati. Il token è breve (ES384, al massimo 120 secondi), riporta lo scope dpp:registry:read ed è indirizzato all'origine HTTPS del tuo host. Lo convalidi solo rispetto alle chiavi del JWKS pubblicato dalla Commissione, mai rispetto a chiavi indicate all'interno del token.

Le regole di risposta sono rigide. Nessun token: restituisci il passaporto pubblico. Token valido e richiedente autorizzato: restituisci dati pubblici più riservati. Un token presente ma non valido: restituisci 401, senza ripiego sulla vista pubblica. Token valido con scope o richiedente sbagliati: 403. Invia Vary: Authorization in modo che le cache tengano separate le due versioni, e usa TLS 1.2 o successivo. JSON è il formato di risposta di base; sono accettati anche JSON-LD e XML.

La guida descrive un solo chiamante, il registro stesso. Non spiega come si autenticheranno le autorità, i riciclatori o le altre parti con un interesse legittimo, quindi ti servirà una risposta separata per loro; la nostra guida ai diritti di accesso al passaporto digitale di prodotto spiega chi ha diritto a cosa. Nemmeno gli identificativi univoci degli operatori vengono ancora elaborati; la guida li prevede per una versione futura.

Dove si inserisce GS1 Digital Link

Il registro segue i reindirizzamenti, al massimo tre sull'intera risoluzione, e risolve l'UPI e ogni reindirizzamento senza credenziali, quindi ogni passaggio deve essere raggiungibile pubblicamente. Questo è compatibile con un resolver. Un URI GS1 Digital Link sul tuo dominio, come https://id.yourbrand.com/01/09520123456788/21/SN0001, è un modo per dare a ogni batteria un identificativo HTTPS persistente che porta al suo passaporto e funziona anche come QR code sul prodotto. Non è obbligatorio; qualsiasi URL HTTPS stabile soddisfa la regola di formato dell'API. Se usi un resolver, conta i passaggi: una catena dal dominio del QR al resolver al fornitore di hosting all'URL finale li usa già tutti e tre. La guida consiglia inoltre di evitare reindirizzamenti dopo l'autenticazione, quindi la richiesta autorizzata dovrebbe arrivare direttamente al passaporto.

Rispetto a quali modelli di dati convalida il registro?

Lo ZIP Semantic Data Artifacts contiene i modelli che il registro verifica. Oggi ne esistono solo due: un modello core e un modello batteries, entrambi 1.0.0, con schemi per i sottogruppi delle batterie EV, LMT e industriali. Ciascuno è fornito come JSON Schema (draft 2020-12), contesti JSON-LD, shape SHACL e vocabolari SKOS, più un catalogo DCAT-AP. La guida descrive anche XSD, che non è incluso in questa versione.

Gli schemi sono suddivisi per livello di accesso: una vista pubblica (pub) e tre viste riservate (res1, res2, res3). Il tuo passaporto deve presentare i campi giusti al richiedente giusto, e lo schema ti dice quali campi stanno dove. Lo ZIP include anche istanze di esempio conformi a ciascuno schema, che sono un buon primo set di dati di test.

Sono descritte quattro serializzazioni (JSON, JSON-LD, XML e RDF), ma solo JSON è obbligatorio per la registrazione, in linea con la EN 18216:2026. La guida cita anche la EN 18223:2026 sull'interoperabilità. Spieghiamo entrambe le norme nella guida alle norme CEN sul DPP, e perché i dati strutturati sono importanti nella nostra guida al passaporto digitale di prodotto leggibile da macchina. L'articolo 12 del regolamento di esecuzione aggiunge che il repository semantico è di uso gratuito e dispone di API pubbliche.

Che cosa aggiungono le linee guida sulle batterie v3.2?

Il documento Guidance Document: Digital Batteries Passport, data points by category, versione 3.2 del 19 ottobre 2026, elenca 71 dati per le batterie EV, LMT e industriali. Si tratta di linee guida e dichiara esso stesso di non essere giuridicamente vincolante; gli obblighi derivano dal regolamento sulle batterie (UE) 2023/1542.

Per ogni dato e categoria di batteria indica uno stato: obbligatorio; facoltativo, da compilare se il dato è disponibile; se applicabile; solo per determinati tipi di batteria; oppure da non compilare né visualizzare a febbraio 2027. Quest'ultimo stato è quello utile per la pianificazione. La dichiarazione e l'etichetta relative all'impronta di carbonio, per esempio, sono indicate come da non compilare a febbraio 2027 perché il loro formato attende ancora un atto di esecuzione, e le istruzioni per l'uso sono sospese in attesa dell'Omnibus. Ogni dato riporta anche un livello di accesso: pubblico, riservato alle persone con un interesse legittimo, agli organismi notificati, alle autorità degli Stati membri e alla Commissione, oppure livelli riservati più ristretti. Sono questi i livelli che le viste di schema pub e res implementano.

La nostra guida al passaporto della batteria tratta i requisiti giuridici. Per il lavoro di integrazione, usa la v3.2 come tabella di corrispondenza tra i tuoi dati di prodotto e i campi dello schema.

Che cosa è deciso e che cosa è ancora aperto?

Deciso: gli endpoint, il modello di autenticazione, la regola del batch atomico, il polling, il modello di dati delle batterie e il requisito che i passaporti siano online al momento dell'invio. La verifica tramite sigillo qualificato è prevista dal regolamento di esecuzione stesso.

Ancora aperto a novembre 2026: come funzionerà tecnicamente la registrazione da parte di terzi verificati per conto di un operatore, i modelli di dati per tutto ciò che non sono batterie, il formato dell'impronta di carbonio, come le altre parti si autenticano presso i passaporti ospitati in proprio e gli identificativi univoci degli operatori. Il regolamento di esecuzione copre anche i prodotti da costruzione, i giocattoli e i detergenti, che non hanno ancora un modello di dati; per i prodotti diversi dalle batterie, gli obblighi decorrono almeno 18 mesi dopo ciascun atto delegato. Gli Stati membri devono designare i propri amministratori nazionali del registro entro il 18 febbraio 2027 (articolo 7).

Le imperfezioni dei documenti della versione 1.0

Una prima versione presenta sempre incoerenze, e queste conviene conoscerle prima di scrivere codice:

• La guida Service Account indica come base dell'API reg.product-passport.ec.europa.eu, mentre i file OpenAPI usano registry.product-passport.ec.europa.eu (e registry.acc.product-passport.ec.europa.eu per l'ambiente di accettazione). Verifica il valore attuale nel registro prima di configurare la produzione.
• Il limite di 100 elementi è indicato nella guida ma non imposto nello schema OpenAPI, quindi un client generato dallo schema costruirà senza problemi una richiesta da 101 elementi.
• La guida all'integrazione dice che gli errori restituiscono l'identificativo come traceId, mentre lo schema di errore OpenAPI lo chiama correlationId. Registrali entrambi nei log.
• L'API usa il codice di sottogruppo EV, mentre gli artefatti semantici usano evb nei loro percorsi. Mappali esplicitamente.

Nessuno di questi punti blocca l'integrazione, ma ricontrollali a ogni nuova versione dei documenti.

Che cosa fare adesso

1. Ottieni un sigillo elettronico qualificato da un prestatore di servizi fiduciari qualificato, se la tua azienda non ne possiede già uno, e verifica la tua organizzazione nel registro. È la voce con i tempi più lunghi di tutto questo elenco.
2. Iscriviti all'ambiente di accettazione e nomina un amministratore che possa creare account di servizio.
3. Decidi dove risiedono i passaporti: sul tuo server, che dovrà allora implementare le regole di autenticazione per l'hosting in proprio, oppure presso un fornitore che lo fa già.
4. Definisci i tuoi UPI. Scegli uno schema di URL HTTPS stabile per ogni batteria, decidi la granularità per articolo, lotto o modello e conta i reindirizzamenti nella catena.
5. Mappa i tuoi dati sulla v3.2 e sugli schemi batteries, campo per campo, comprese le viste pubbliche e riservate. Segna ciò che non è richiesto a febbraio 2027, così nessuno ci perde tempo.
6. Convalida in locale prima di inviare, rispetto ai JSON Schema forniti, e progetta i batch in modo che un record errato non blocchi gli altri.
7. Costruisci il client come si deve: chiavi EC in un HSM, rinnovo dei token, chiavi di idempotenza riproducibili, polling secondo Fibonacci e archiviazione di ogni prova di registrazione.
8. Esegui un test completo nell'ambiente di accettazione con largo anticipo rispetto al 18 febbraio 2027, compresi un batch fallito e una rotazione delle chiavi.

Digital Link è un solution partner GS1, e la nostra piattaforma costruisce passaporti delle batterie e dei prodotti su un identificativo GS1 Digital Link persistente per ogni prodotto, con dati pubblici e riservati serviti dallo stesso record. Stiamo preparando la nostra integrazione con il registro. Questo comporta tre passaggi distinti: ottenere il nostro sigillo elettronico qualificato, completare la nostra verifica nel registro, e costruire e testare la connessione API. Non siamo ancora collegati al registro. Se vuoi pianificare la tua integrazione con il registro, o verificare se i dati dei tuoi passaporti supereranno la convalida, contattaci e il nostro team esaminerà il tuo caso.

Domande frequenti

L'API del registro DPP è obbligatoria?

No. L'articolo 8, paragrafo 6, del regolamento di esecuzione (UE) 2026/1778 consente la registrazione tramite l'interfaccia utente o l'API. In pratica, chiunque registri più di una manciata di passaporti vorrà usare l'API.

Il registro conserva i dati del mio passaporto?

No. Recupera il passaporto dal suo URL al momento dell'invio per convalidarlo, e la guida all'integrazione afferma che non conserva in modo persistente il contenuto recuperato. Il passaporto resta dove lo ospiti, ed è per questo che deve essere raggiungibile al momento dell'invio.

Posso usare una chiave RSA o un client secret per il mio account di servizio?

No. Gli account di servizio si autenticano con private_key_jwt usando chiavi a curva ellittica (ES256, ES384 o ES512). I client secret condivisi e le chiavi RSA non sono supportati.

Che cosa succede se un passaporto di un batch non supera la convalida?

L'intero invio fallisce e nessuno dei suoi passaporti viene registrato. L'attività si completa con esito FAILED, e i risultati per elemento ti dicono quali elementi l'hanno causato. Correggili e reinvia con una nuova chiave di idempotenza.

Mi serve GS1 Digital Link per registrare un passaporto?

No. L'identificativo univoco del prodotto deve essere un URL HTTPS che risolve al passaporto. Un URI GS1 Digital Link sul tuo dominio è un modo per soddisfare questo requisito, e funge anche da QR code del prodotto, ma è accettato qualsiasi URL HTTPS stabile.

Quando devono essere registrati i passaporti delle batterie?

Per le batterie per veicoli elettrici, le batterie LMT e le batterie industriali superiori a 2 kWh, l'obbligo del passaporto della batteria ai sensi del regolamento (UE) 2023/1542 si applica dal 18 febbraio 2027. Il registro e il suo ambiente di accettazione sono già aperti, quindi c'è tempo per testare prima.