Dokumentation for passplatforme
dpp-backup.com tilbyder livscykluskaldene i EN 18222. En platform sender pas med CreateDPP og UpdateDPPById, og fire læsekald svarer fra kopien. Hver gemt version returneres med en kvittering signeret med Ed25519.
Det grundlæggende
- Adresse:
https://dpp-backup.com/api/v1 - Adgangsnøgle:
Authorization: Bearer <credential>. Brandet opretter forbindelsen i sin portal og giver dig adgangsnøglen. Den fører til netop det brands kopi og ingen andre steder. - Indhold: JSON, højst 1.048.576 byte.
- Stier: som i EN 18222 tabel 16. Procentkod et id i stien.
Afsendelse af pas
| EN 18222-kald | Forespørgsel | Svar |
|---|---|---|
| CreateDPP (4.6) | POST /api/v1/dpps med hele passet | 201 og den gemte version |
| UpdateDPPById (4.7) | PATCH /api/v1/dpps/{dppId} med de dele, der er ændret | 200 og passet, som det er gemt |
| DeleteDPPById (4.8) | DELETE /api/v1/dpps/{dppId} | Altid 405. En sikkerhedskopi opbevares i hele passets levetid. |
En opdatering er en JSON merge patch (RFC 7396), som EN 18222 8.1 foreslår. En null fjerner et medlem. Patchen flettes ind i den nyeste gemte version, og resultatet gemmes som den næste version. Hvis det flettede pas ikke er gyldigt, gemmes intet.
Hvad et pas skal have
Attributterne i EN 18223 tabel 1:
digitalProductPassportId: en streng på højst 500 tegn. Den kan ikke ændres i en opdatering.uniqueProductIdentifier: for eksempel en GS1 Digital Link-adresse.granularity:model,batchelleritem.dppSchemaVersiondppStatus:active,inactive,archivedellerinvalid. Kun offentliggjorte pas sikkerhedskopieres, så en kladde afvises.lastUpdated: ISO 8601 med tidszone, for eksempel2026-11-16T09:00:00Z. Den gemmes, men en versions tidspunkt er det tidspunkt, hvor den blev gemt.economicOperatorId- Når de er angivet:
facilityId(en streng) ogcontentSpecificationIds(en liste af strenge).
Alt andet i passet er et dataelement og gemmes, som det blev sendt.
Hvad der ikke er offentligt
EN 18222 indeholder ingen egne adgangsregler, så du angiver de dataelementer, der ikke er offentlige, i ét ekstra medlem, x-backup. Det er ikke et dataelement og offentliggøres aldrig.
"x-backup": { "withheldFromPublic": ["supplierPrice", "factoryAudit"] }
EN 18221 4.3 kræver, at kopien bevarer det oprindelige pas' adgangsbegrænsninger, og det er gennem denne liste, kopien kender dem. Uden den viser vi ingen produktdata fra den version offentligt i stedet for at gætte. I en opdatering forbliver et medlem, du udelader, som det var.
Vedhæftede dokumenter (EN 18221 4.4): hvordan filerne sendes, er endnu ikke beskrevet her. Kommer
Send et kald igen
En oprettelse eller en opdatering kan have en Idempotency-Key-header på 1 til 200 skrivbare tegn. Samme nøgle med samme forespørgsel giver det første svar igen, med Idempotent-Replay: true, og intet nyt gemmes. Samme nøgle med en anden forespørgsel afvises.
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..."
}
}
Læsning fra kopien
| EN 18222-kald | Forespørgsel |
|---|---|
| ReadDPPById (4.2) | GET /api/v1/dpps/{dppId} |
| ReadDPPByProductId (4.3) | GET /api/v1/dppsByProductId/{productId}, et GTIN på 8 til 14 cifre eller en GS1 Digital Link-adresse |
| ReadDPPIdsByProductIds (4.5) | POST /api/v1/dppsByProductIds med {"productIds": ["09506000134352"]}, højst 1.000 GTIN |
| ReadDPPVersionByIdAndDate (4.4) | GET /api/v1/dppsByIdAndDate/{dppId}?date=2026-11-14T12:00:00Z |
Et læsekald svarer med den nyeste version, eller for en dato den version, der var gældende dengang. Bed om application/json, application/ld+json eller text/html i Accept-headeren (indholdsforhandling efter EN 18216). Hvert svar oplyser, at det er sikkerhedskopien, hvilken version det er, og SHA-256-hashen af indholdet.
Passets egen adresse virker også: /01/{gtin} med GS1 Digital Link-nøglerne efter.
Læsekaldene svarer på et domæne, der er åbnet for læsning. Et domæne åbnes, når et brand peger sit pasdomæne mod kopien. Alle andre steder svarer et læsekald 404.
Tilbydes ikke: ReadDataElement og UpdateDataElement (EN 18222 afsnit 6).
Kvitteringer
Hver gemt version får en kvittering. Den består af to dele, forbundet med et punktum, hver i base64url uden udfyldning:
base64url(receipt as JSON) "." base64url(Ed25519 signature over the first part, as written)
Signaturen dækker den første del præcis som skrevet, så intet skal sorteres før kontrollen. JSON-delen indeholder:
| Felt | Hvad det er |
|---|---|
v | Formatversionen, nu 1 |
key_id | Nøglen, der signerede den |
receipt_id | Id for den gemte version |
sender | Hvem der sendte versionen |
dpp_id | digitalProductPassportId |
version_number | Versionens nummer, fra 1 |
content_sha256 | SHA-256-hashen af indholdet, som hex |
received_at | Hvornår versionen blev gemt |
Den offentlige nøgle
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 hex-cifre af SHA-256-hashen af nøglen i dens SPKI-form. Kontrollér en kvittering på verificeringssiden eller med et hvilket som helst Ed25519-bibliotek.
Fejlkoder
En afvist oprettelse eller opdatering svarer med resultatobjektet fra 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 | Hvornår (oprettelse og opdatering) |
|---|---|
| 400 | Indholdet er ikke et JSON-objekt, en obligatorisk attribut mangler eller er forkert, passet er en kladde, id'et blev ændret, eller Idempotency-Key er ugyldig eller blev brugt med en anden forespørgsel. |
| 401 | Adgangsnøglen er forkert eller mangler. |
| 403 | Forbindelsen gælder ikke længere. |
| 404 | En opdatering af et pas, der ikke opbevares for denne forbindelse. |
| 405 | En sletning eller en metode, der ikke er tilladt på stien. |
| 409 | En oprettelse af et pas, der allerede opbevares, en opdatering, der stødte sammen med en anden opdatering, eller et kald, hvis Idempotency-Key stadig er i gang (med Retry-After). |
| 413 | Indholdet eller passet efter opdateringen er større end 1.048.576 byte. |
| 429 | For mange kald. Vent det antal sekunder, der står i Retry-After. |
| 500 | Passet kunne ikke gemmes. Send det igen; med samme Idempotency-Key gemmes intet to gange. |
Læsekaldene svarer {"error": "…"}:
| Status | Hvornår (læsning) |
|---|---|
| 300 | Mere end ét brand har et pas på denne adresse. Svaret oplister dem. |
| 400 | Id'et, GTIN'et eller datoen mangler eller er ugyldig. |
| 404 | Passet findes ikke i kopien, eller domænet er ikke åbnet for læsning. |
| 405 | En metode, der ikke er tilladt på stien. |
| 413 | Mere end 1.000 produkt-id'er. |
| 429 | For mange forespørgsler. Vent det antal sekunder, der står i Retry-After. |
| 503 | Midlertidigt utilgængelig. Prøv igen efter Retry-After. |
Opbevar en sikkerhedskopi af dine pas
Opret en organisation med din e-mail fra virksomheden. Når den er godkendt, tilslutter du den platform, der har dine pas.
Der kræves en e-mailadresse fra virksomheden. Vores medarbejdere gennemgår nye organisationer på hverdage. Portalen er på engelsk.