Dokumentasjon for passplattformer
dpp-backup.com tilbyr livssykluskallene i EN 18222. En plattform sender pass med CreateDPP og UpdateDPPById, og fire lesekall svarer fra kopien. Hver lagrede versjon kommer tilbake med en kvittering signert med Ed25519.
Det grunnleggende
- Adresse:
https://dpp-backup.com/api/v1 - Tilgangsnøkkel:
Authorization: Bearer <credential>. Merkevaren oppretter tilkoblingen i portalen sin og gir deg tilgangsnøkkelen. Den gir tilgang til den merkevarens kopi og ingenting annet. - Innhold: JSON, maksimalt 1 048 576 byte.
- Stier: som i EN 18222 tabell 16. Prosentkod en id i stien.
Sende pass
| EN 18222-kall | Forespørsel | Svar |
|---|---|---|
| CreateDPP (4.6) | POST /api/v1/dpps med hele passet | 201 og den lagrede versjonen |
| UpdateDPPById (4.7) | PATCH /api/v1/dpps/{dppId} med delene som er endret | 200 og passet slik det er lagret |
| DeleteDPPById (4.8) | DELETE /api/v1/dpps/{dppId} | Alltid 405. En sikkerhetskopi oppbevares i hele passets levetid. |
En oppdatering er en JSON merge patch (RFC 7396), slik EN 18222 8.1 foreslår. En null fjerner et medlem. Patchen flettes inn i den nyeste lagrede versjonen, og resultatet lagres som neste versjon. Hvis det flettede passet ikke er gyldig, lagres ingenting.
Hva et pass må ha
Attributtene i EN 18223 tabell 1:
digitalProductPassportId: en streng på maksimalt 500 tegn. Den kan ikke endres i en oppdatering.uniqueProductIdentifier: for eksempel en GS1 Digital Link-adresse.granularity:model,batchelleritem.dppSchemaVersiondppStatus:active,inactive,archivedellerinvalid. Bare publiserte pass sikkerhetskopieres, så et utkast avvises.lastUpdated: ISO 8601 med tidssone, for eksempel2026-11-16T09:00:00Z. Verdien tas vare på, men tidspunktet for en versjon er tidspunktet den ble lagret.economicOperatorId- Når de er oppgitt:
facilityId(en streng) ogcontentSpecificationIds(en liste med strenger).
Alt annet i passet er dataelementer og lagres slik det ble sendt.
Hva som ikke er offentlig
EN 18222 har ingen egne tilgangsregler, så du lister opp dataelementene som ikke er offentlige, i ett ekstra medlem, x-backup. Det er ikke et dataelement og publiseres aldri.
"x-backup": { "withheldFromPublic": ["supplierPrice", "factoryAudit"] }
EN 18221 4.3 krever at kopien beholder tilgangsbegrensningene til det opprinnelige passet, og det er gjennom denne listen kopien kjenner dem. Uten den viser vi ingen produktdata fra den versjonen offentlig i stedet for å gjette. I en oppdatering forblir et medlem du utelater, som det var.
Vedlagte dokumenter (EN 18221 4.4): hvordan filene sendes, er ikke beskrevet her ennå. Kommer
Sende et kall på nytt
En opprettelse eller en oppdatering kan ha en Idempotency-Key-header på 1 til 200 skrivbare tegn. Samme nøkkel med samme forespørsel gir det første svaret på nytt, med Idempotent-Replay: true, og ingenting nytt lagres. Samme nøkkel med en annen forespørsel avvises.
Et eksempel
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..."
}
}
Lese fra kopien
| EN 18222-kall | Forespørsel |
|---|---|
| ReadDPPById (4.2) | GET /api/v1/dpps/{dppId} |
| ReadDPPByProductId (4.3) | GET /api/v1/dppsByProductId/{productId}, et GTIN på 8 til 14 sifre eller en GS1 Digital Link-adresse |
| ReadDPPIdsByProductIds (4.5) | POST /api/v1/dppsByProductIds med {"productIds": ["09506000134352"]}, maksimalt 1 000 GTIN |
| ReadDPPVersionByIdAndDate (4.4) | GET /api/v1/dppsByIdAndDate/{dppId}?date=2026-11-14T12:00:00Z |
Et lesekall svarer med den nyeste versjonen, eller for en dato den versjonen som gjaldt da. Be om application/json, application/ld+json eller text/html i Accept-headeren (innholdsforhandling etter EN 18216). Hvert svar sier at det er sikkerhetskopien, hvilken versjon det er, og SHA-256-hashen av innholdet.
Passets egen adresse virker også: /01/{gtin} med GS1 Digital Link-nøklene etter.
Lesekallene svarer på et domene som er åpnet for lesing. Et domene åpnes når en merkevare peker passdomenet sitt til kopien. Alle andre steder svarer et lesekall 404.
Tilbys ikke: ReadDataElement og UpdateDataElement (EN 18222 punkt 6).
Kvitteringer
Hver lagrede versjon får en kvittering. Den består av to deler som er satt sammen med et punktum, hver i base64url uten utfylling:
base64url(receipt as JSON) "." base64url(Ed25519 signature over the first part, as written)
Signaturen dekker den første delen nøyaktig slik den er skrevet, så ingenting må sorteres før kontrollen. JSON-en inneholder:
| Felt | Hva det er |
|---|---|
v | Formatversjonen, nå 1 |
key_id | Nøkkelen som signerte den |
receipt_id | ID-en til den lagrede versjonen |
sender | Hvem som sendte versjonen |
dpp_id | digitalProductPassportId |
version_number | Versjonsnummeret, fra 1 |
content_sha256 | SHA-256-hashen av innholdet, heksadesimalt |
received_at | Når versjonen ble lagret |
Den offentlige nøkkelen
GET /.well-known/backup-receipt-key svarer:
{
"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 er de første 16 heksadesimale sifrene i SHA-256-hashen av nøkkelen i SPKI-form. Kontroller en kvittering på kontrollsiden, eller med et hvilket som helst Ed25519-bibliotek.
Feilkoder
En avvist opprettelse eller oppdatering svarer med resultatobjektet i EN 18222 7.2:
{
"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"
}
]
}
| Status | Når (opprettelse og oppdatering) |
|---|---|
| 400 | Innholdet er ikke et JSON-objekt, et obligatorisk attributt mangler eller er feil, passet er et utkast, ID-en ble endret, eller Idempotency-Key er ugyldig eller ble brukt med en annen forespørsel. |
| 401 | Tilgangsnøkkelen er feil eller mangler. |
| 403 | Tilkoblingen gjelder ikke lenger. |
| 404 | En oppdatering av et pass som ikke oppbevares for denne tilkoblingen. |
| 405 | En sletting, eller en metode som ikke er tillatt på stien. |
| 409 | En opprettelse av et pass som allerede oppbevares, en oppdatering som kolliderte med en annen oppdatering, eller et kall der Idempotency-Key fortsatt behandles (med Retry-After). |
| 413 | Innholdet, eller passet etter oppdateringen, er større enn 1 048 576 byte. |
| 429 | For mange kall. Vent det antallet sekunder som står i Retry-After. |
| 500 | Passet kunne ikke lagres. Send det på nytt; med samme Idempotency-Key lagres ingenting to ganger. |
Lesekallene svarer {"error": "…"}:
| Status | Når (lesing) |
|---|---|
| 300 | Mer enn én merkevare har et pass på denne adressen. Svaret lister dem opp. |
| 400 | ID-en, GTIN-et eller datoen mangler eller er ugyldig. |
| 404 | Passet finnes ikke i kopien, eller domenet er ikke åpnet for lesing. |
| 405 | En metode som ikke er tillatt på stien. |
| 413 | Mer enn 1 000 produkt-ID-er. |
| 429 | For mange forespørsler. Vent det antallet sekunder som står i Retry-After. |
| 503 | Midlertidig utilgjengelig. Prøv igjen etter Retry-After. |
Ta vare på en sikkerhetskopi av passene dine
Opprett en organisasjon med jobb-e-posten din. Når den er godkjent, kobler du til plattformen som har passene dine.
Du må bruke en jobb-e-postadresse. Våre medarbeidere går gjennom nye organisasjoner på virkedager. Portalen er på engelsk.