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 18222RichiestaRisposta
CreateDPP (4.6)POST /api/v1/dpps con il passaporto completo201 e la versione archiviata
UpdateDPPById (4.7)PATCH /api/v1/dpps/{dppId} con le parti modificate200 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, batch o item.
  • dppSchemaVersion
  • dppStatus: active, inactive, archived o invalid. Solo i passaporti pubblicati vengono sottoposti a backup, quindi una bozza viene rifiutata.
  • lastUpdated: ISO 8601 con un fuso orario, per esempio 2026-11-16T09:00:00Z. Viene conservato, ma il momento di una versione è quello in cui è stata archiviata.
  • economicOperatorId
  • Se presenti: facilityId (una stringa) e contentSpecificationIds (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 18222Richiesta
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:

CampoChe cos'è
vLa versione del formato, attualmente 1
key_idLa chiave che l'ha firmata
receipt_idL'id della versione archiviata
senderChi ha inviato la versione
dpp_idIl digitalProductPassportId
version_numberIl numero della versione, a partire da 1
content_sha256L'hash SHA-256 del contenuto, in esadecimale
received_atQuando 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"
    }
  ]
}
StatoQuando (creazione e aggiornamento)
400Il 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.
401La credenziale è errata o mancante.
403Il collegamento non è più attivo.
404Un aggiornamento per un passaporto che non è conservato per questo collegamento.
405Una cancellazione, o un metodo non consentito sul percorso.
409Una 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).
413Il corpo, o il passaporto dopo l'aggiornamento, supera 1.048.576 byte.
429Troppe chiamate. Attendete i secondi indicati in Retry-After.
500Il passaporto non è stato archiviato. Inviatelo di nuovo; con la stessa Idempotency-Key nulla viene archiviato due volte.

Le chiamate di lettura rispondono {"error": "…"}:

StatoQuando (letture)
300Più di un marchio detiene un passaporto a questo indirizzo. La risposta li elenca.
400L'id, il GTIN o la data mancano o non sono validi.
404Il passaporto non è conservato nella copia, oppure il dominio non è aperto alla lettura.
405Un metodo non consentito sul percorso.
413Più di 1.000 id di prodotto.
429Troppe richieste. Attendete i secondi indicati in Retry-After.
503Temporaneamente 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.