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-kaldForespørgselSvar
CreateDPP (4.6)POST /api/v1/dpps med hele passet201 og den gemte version
UpdateDPPById (4.7)PATCH /api/v1/dpps/{dppId} med de dele, der er ændret200 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, batch eller item.
  • dppSchemaVersion
  • dppStatus: active, inactive, archived eller invalid. Kun offentliggjorte pas sikkerhedskopieres, så en kladde afvises.
  • lastUpdated: ISO 8601 med tidszone, for eksempel 2026-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) og contentSpecificationIds (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-kaldForespø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:

FeltHvad det er
vFormatversionen, nu 1
key_idNøglen, der signerede den
receipt_idId for den gemte version
senderHvem der sendte versionen
dpp_iddigitalProductPassportId
version_numberVersionens nummer, fra 1
content_sha256SHA-256-hashen af indholdet, som hex
received_atHvornå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"
    }
  ]
}
StatusHvornår (oprettelse og opdatering)
400Indholdet 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.
401Adgangsnøglen er forkert eller mangler.
403Forbindelsen gælder ikke længere.
404En opdatering af et pas, der ikke opbevares for denne forbindelse.
405En sletning eller en metode, der ikke er tilladt på stien.
409En 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).
413Indholdet eller passet efter opdateringen er større end 1.048.576 byte.
429For mange kald. Vent det antal sekunder, der står i Retry-After.
500Passet kunne ikke gemmes. Send det igen; med samme Idempotency-Key gemmes intet to gange.

Læsekaldene svarer {"error": "…"}:

StatusHvornår (læsning)
300Mere end ét brand har et pas på denne adresse. Svaret oplister dem.
400Id'et, GTIN'et eller datoen mangler eller er ugyldig.
404Passet findes ikke i kopien, eller domænet er ikke åbnet for læsning.
405En metode, der ikke er tilladt på stien.
413Mere end 1.000 produkt-id'er.
429For mange forespørgsler. Vent det antal sekunder, der står i Retry-After.
503Midlertidigt 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.