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-kallForespørselSvar
CreateDPP (4.6)POST /api/v1/dpps med hele passet201 og den lagrede versjonen
UpdateDPPById (4.7)PATCH /api/v1/dpps/{dppId} med delene som er endret200 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, batch eller item.
  • dppSchemaVersion
  • dppStatus: active, inactive, archived eller invalid. Bare publiserte pass sikkerhetskopieres, så et utkast avvises.
  • lastUpdated: ISO 8601 med tidssone, for eksempel 2026-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) og contentSpecificationIds (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-kallForespø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:

FeltHva det er
vFormatversjonen, nå 1
key_idNøkkelen som signerte den
receipt_idID-en til den lagrede versjonen
senderHvem som sendte versjonen
dpp_iddigitalProductPassportId
version_numberVersjonsnummeret, fra 1
content_sha256SHA-256-hashen av innholdet, heksadesimalt
received_atNå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"
    }
  ]
}
StatusNår (opprettelse og oppdatering)
400Innholdet 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.
401Tilgangsnøkkelen er feil eller mangler.
403Tilkoblingen gjelder ikke lenger.
404En oppdatering av et pass som ikke oppbevares for denne tilkoblingen.
405En sletting, eller en metode som ikke er tillatt på stien.
409En 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).
413Innholdet, eller passet etter oppdateringen, er større enn 1 048 576 byte.
429For mange kall. Vent det antallet sekunder som står i Retry-After.
500Passet kunne ikke lagres. Send det på nytt; med samme Idempotency-Key lagres ingenting to ganger.

Lesekallene svarer {"error": "…"}:

StatusNår (lesing)
300Mer enn én merkevare har et pass på denne adressen. Svaret lister dem opp.
400ID-en, GTIN-et eller datoen mangler eller er ugyldig.
404Passet finnes ikke i kopien, eller domenet er ikke åpnet for lesing.
405En metode som ikke er tillatt på stien.
413Mer enn 1 000 produkt-ID-er.
429For mange forespørsler. Vent det antallet sekunder som står i Retry-After.
503Midlertidig 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.