Documentazione per le piattaforme per i passaporti
dpp-backup.com offre le chiamate del ciclo di vita della EN 18222. Una piattaforma invia i passaporti con CreateDPP e UpdateDPPById, e quattro chiamate di lettura rispondono dalla copia. Ogni versione archiviata viene restituita con una ricevuta firmata con Ed25519.
Gli elementi di base
- Indirizzo:
https://dpp-backup.com/api/v1 - Credenziale:
Authorization: Bearer <credential>. Il marchio crea il collegamento nel proprio portale e vi fornisce la credenziale. Essa porta alla copia di quel marchio e a nient'altro. - Corpo: JSON, al massimo 1.048.576 byte.
- Percorsi: come nella tabella 16 della EN 18222. Codificate con percent-encoding un id nel percorso.
Invio dei passaporti
| Chiamata EN 18222 | Richiesta | Risposta |
|---|---|---|
| CreateDPP (4.6) | POST /api/v1/dpps con il passaporto completo | 201 e la versione archiviata |
| UpdateDPPById (4.7) | PATCH /api/v1/dpps/{dppId} con le parti modificate | 200 e il passaporto come archiviato |
| DeleteDPPById (4.8) | DELETE /api/v1/dpps/{dppId} | Sempre 405. Una copia di backup è conservata per tutta la durata del passaporto. |
Un aggiornamento è un JSON merge patch (RFC 7396), come suggerisce il punto 8.1 della EN 18222. Un null rimuove un membro. La patch viene unita all'ultima versione archiviata e il risultato viene archiviato come versione successiva. Se il passaporto risultante non è valido, non viene archiviato nulla.
Che cosa deve contenere un passaporto
Gli attributi della tabella 1 della EN 18223:
digitalProductPassportId: una stringa di al massimo 500 caratteri. Non può cambiare in un aggiornamento.uniqueProductIdentifier: per esempio un indirizzo GS1 Digital Link.granularity:model,batchoitem.dppSchemaVersiondppStatus:active,inactive,archivedoinvalid. Solo i passaporti pubblicati vengono sottoposti a backup, quindi una bozza viene rifiutata.lastUpdated: ISO 8601 con un fuso orario, per esempio2026-11-16T09:00:00Z. Viene conservato, ma il momento di una versione è quello in cui è stata archiviata.economicOperatorId- Se presenti:
facilityId(una stringa) econtentSpecificationIds(un elenco di stringhe).
Tutto il resto del passaporto è un elemento di dati ed è archiviato così come è stato inviato.
Che cosa non è pubblico
La EN 18222 non prevede regole di accesso proprie, quindi gli elementi di dati non pubblici si elencano in un membro aggiuntivo, x-backup. Non è un elemento di dati e non viene mai pubblicato.
"x-backup": { "withheldFromPublic": ["supplierPrice", "factoryAudit"] }
Il punto 4.3 della EN 18221 chiede che la copia mantenga le restrizioni di accesso del passaporto originale, e questo elenco è il modo in cui la copia le conosce. Senza di esso non mostriamo pubblicamente alcun dato di prodotto di quella versione, anziché tirare a indovinare. In un aggiornamento, un membro omesso resta com'era.
Documenti allegati (EN 18221, punto 4.4): le modalità di invio dei relativi file non sono ancora descritte qui. In arrivo
Inviare di nuovo una chiamata
Una creazione o un aggiornamento può contenere un'intestazione Idempotency-Key da 1 a 200 caratteri stampabili. La stessa chiave con la stessa richiesta riceve di nuovo la prima risposta, con Idempotent-Replay: true, e non viene archiviato nulla di nuovo. La stessa chiave con un'altra richiesta viene rifiutata.
Un esempio
POST /api/v1/dpps HTTP/1.1
Host: dpp-backup.com
Authorization: Bearer <credential>
Content-Type: application/json
Idempotency-Key: 2f1f3c9b-create-1
{
"digitalProductPassportId": "5b1d3a8e-0c3f-4a8e-9a77-2f1f3c9b7e01",
"uniqueProductIdentifier": "https://id.example.com/01/09506000134352/21/ABC123",
"granularity": "item",
"dppSchemaVersion": "1.0",
"dppStatus": "active",
"lastUpdated": "2026-11-16T09:00:00Z",
"economicOperatorId": "urn:example:operator:4012345000009",
"x-backup": { "withheldFromPublic": ["supplierPrice"] },
"productName": "Wool jumper",
"supplierPrice": "internal"
}
HTTP/1.1 201 Created
Backup-Receipt: eyJ2IjoxLCJrZXlfaWQiOi...
{
"digitalProductPassportId": "5b1d3a8e-0c3f-4a8e-9a77-2f1f3c9b7e01",
"x-backup": {
"versionNumber": 1,
"receivedAt": "2026-11-16T09:00:01.482Z",
"versionId": "0d6e7a52-5b0c-4f7e-9d0e-8a3c1f9b2c44",
"contentSha256": "3b5d…64 hex digits…9f1c",
"receipt": "eyJ2IjoxLCJrZXlfaWQiOi..."
}
}
Lettura dalla copia
| Chiamata EN 18222 | Richiesta |
|---|---|
| ReadDPPById (4.2) | GET /api/v1/dpps/{dppId} |
| ReadDPPByProductId (4.3) | GET /api/v1/dppsByProductId/{productId}, un GTIN da 8 a 14 cifre o un indirizzo GS1 Digital Link |
| ReadDPPIdsByProductIds (4.5) | POST /api/v1/dppsByProductIds con {"productIds": ["09506000134352"]}, al massimo 1.000 GTIN |
| ReadDPPVersionByIdAndDate (4.4) | GET /api/v1/dppsByIdAndDate/{dppId}?date=2026-11-14T12:00:00Z |
Una lettura restituisce la versione più recente o, per una data, la versione in vigore in quel momento. Richiedete application/json, application/ld+json o text/html nell'intestazione Accept (negoziazione del contenuto secondo la EN 18216). Ogni risposta indica che si tratta della copia di backup, di quale versione si tratta e l'hash SHA-256 del suo contenuto.
Funziona anche l'indirizzo proprio del passaporto: /01/{gtin} seguito dalle chiavi GS1 Digital Link.
Le chiamate di lettura rispondono su un dominio aperto alla lettura. Un dominio viene aperto quando un marchio fa puntare il proprio dominio dei passaporti verso la copia. Altrove, una lettura risponde 404.
Non offerte: ReadDataElement e UpdateDataElement (EN 18222, punto 6).
Ricevute
Ogni versione archiviata riceve una ricevuta. È composta da due parti unite da un punto, ciascuna in base64url senza padding:
base64url(receipt as JSON) "." base64url(Ed25519 signature over the first part, as written)
La firma copre la prima parte esattamente come è scritta, quindi nulla deve essere riordinato prima della verifica. Il JSON contiene:
| Campo | Che cos'è |
|---|---|
v | La versione del formato, attualmente 1 |
key_id | La chiave che l'ha firmata |
receipt_id | L'id della versione archiviata |
sender | Chi ha inviato la versione |
dpp_id | Il digitalProductPassportId |
version_number | Il numero della versione, a partire da 1 |
content_sha256 | L'hash SHA-256 del contenuto, in esadecimale |
received_at | Quando la versione è stata archiviata |
La chiave pubblica
GET /.well-known/backup-receipt-key risponde:
{
"algorithm": "Ed25519",
"key_id": "…16 hex digits…",
"public_key_spki_base64": "MCowBQYDK2VwAyEA…",
"receipt_format": "base64url(JSON) \".\" base64url(signature over the first part as written)"
}
key_id sono le prime 16 cifre esadecimali dell'hash SHA-256 della chiave nella sua forma SPKI. Verificate una ricevuta nella pagina di verifica o con una qualsiasi libreria Ed25519.
Codici di errore
Una creazione o un aggiornamento rifiutati rispondono con l'oggetto risultato del punto 7.2 della EN 18222:
{
"message": [
{
"messageType": "Error",
"text": "dppStatus is \"draft\". Drafts are not backed up: send the passport when it is published",
"code": "400",
"timestamp": "2026-11-16T09:00:01.482Z"
}
]
}
| Stato | Quando (creazione e aggiornamento) |
|---|---|
| 400 | Il corpo non è un oggetto JSON, un attributo obbligatorio manca o è errato, il passaporto è una bozza, l'id è stato modificato, oppure la Idempotency-Key non è valida o è stata usata con un'altra richiesta. |
| 401 | La credenziale è errata o mancante. |
| 403 | Il collegamento non è più attivo. |
| 404 | Un aggiornamento per un passaporto che non è conservato per questo collegamento. |
| 405 | Una cancellazione, o un metodo non consentito sul percorso. |
| 409 | Una creazione per un passaporto già conservato, un aggiornamento entrato in conflitto con un altro aggiornamento, o una chiamata la cui Idempotency-Key è ancora in elaborazione (con Retry-After). |
| 413 | Il corpo, o il passaporto dopo l'aggiornamento, supera 1.048.576 byte. |
| 429 | Troppe chiamate. Attendete i secondi indicati in Retry-After. |
| 500 | Il passaporto non è stato archiviato. Inviatelo di nuovo; con la stessa Idempotency-Key nulla viene archiviato due volte. |
Le chiamate di lettura rispondono {"error": "…"}:
| Stato | Quando (letture) |
|---|---|
| 300 | Più di un marchio detiene un passaporto a questo indirizzo. La risposta li elenca. |
| 400 | L'id, il GTIN o la data mancano o non sono validi. |
| 404 | Il passaporto non è conservato nella copia, oppure il dominio non è aperto alla lettura. |
| 405 | Un metodo non consentito sul percorso. |
| 413 | Più di 1.000 id di prodotto. |
| 429 | Troppe richieste. Attendete i secondi indicati in Retry-After. |
| 503 | Temporaneamente non disponibile. Riprovate dopo Retry-After. |
Conservate una copia di backup dei vostri passaporti
Create un'organizzazione con la vostra email aziendale. Una volta approvata, collegate la piattaforma che gestisce i vostri passaporti.
È richiesto un indirizzo email aziendale. Il nostro personale esamina le nuove organizzazioni nei giorni lavorativi. Il portale è in inglese.