Dokumentation för passplattformar

dpp-backup.com erbjuder livscykelanropen i EN 18222. En plattform skickar pass med CreateDPP och UpdateDPPById, och fyra läsanrop svarar från kopian. Varje lagrad version returneras med ett kvitto signerat med Ed25519.

Grunderna

  • Adress: https://dpp-backup.com/api/v1
  • Åtkomstnyckel: Authorization: Bearer <credential>. Varumärket skapar anslutningen i sin portal och ger dig åtkomstnyckeln. Den leder till det varumärkets kopia och ingen annanstans.
  • Innehåll: JSON, högst 1 048 576 byte.
  • Sökvägar: enligt tabell 16 i EN 18222. Procentkoda ett id i sökvägen.

Skicka pass

Anrop i EN 18222BegäranSvar
CreateDPP (4.6)POST /api/v1/dpps med hela passet201 och den lagrade versionen
UpdateDPPById (4.7)PATCH /api/v1/dpps/{dppId} med de delar som ändrats200 och passet som det lagrats
DeleteDPPById (4.8)DELETE /api/v1/dpps/{dppId}Alltid 405. En säkerhetskopia sparas under passets hela livslängd.

En uppdatering är en JSON merge patch (RFC 7396), som EN 18222 8.1 föreslår. Ett null tar bort en medlem. Patchen slås samman med den senast lagrade versionen, och resultatet lagras som nästa version. Om det sammanslagna passet inte är giltigt lagras ingenting.

Vad ett pass måste ha

Attributen i tabell 1 i EN 18223:

  • digitalProductPassportId: en sträng på högst 500 tecken. Den kan inte ändras i en uppdatering.
  • uniqueProductIdentifier: till exempel en adress enligt GS1 Digital Link.
  • granularity: model, batch eller item.
  • dppSchemaVersion
  • dppStatus: active, inactive, archived eller invalid. Bara publicerade pass säkerhetskopieras, så ett utkast avvisas.
  • lastUpdated: ISO 8601 med tidszon, till exempel 2026-11-16T09:00:00Z. Värdet sparas, men en versions tidpunkt är tidpunkten då den lagrades.
  • economicOperatorId
  • Om de anges: facilityId (en sträng) och contentSpecificationIds (en lista med strängar).

Allt annat i passet är dataelement och lagras som det skickades.

Vad som inte är publikt

EN 18222 har inga egna åtkomstregler, så du listar de dataelement som inte är publika i en extra medlem, x-backup. Den är inget dataelement och publiceras aldrig.

"x-backup": { "withheldFromPublic": ["supplierPrice", "factoryAudit"] }

EN 18221 4.3 kräver att kopian behåller originalpassets åtkomstbegränsningar, och den här listan är hur kopian känner till dem. Utan den visar vi inga produktdata från den versionen publikt, i stället för att gissa. I en uppdatering förblir en medlem som du utelämnar som den var.

Bifogade dokument (EN 18221 4.4): hur deras filer skickas beskrivs inte här än. Kommer

Skicka ett anrop igen

En skapelse eller en uppdatering kan ha en Idempotency-Key-header på 1 till 200 skrivbara tecken. Samma nyckel med samma begäran får det första svaret igen, med Idempotent-Replay: true, och inget nytt lagras. Samma nyckel med en annan begäran avvisas.

Ett exempel

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äsa från kopian

Anrop i EN 18222Begäran
ReadDPPById (4.2)GET /api/v1/dpps/{dppId}
ReadDPPByProductId (4.3)GET /api/v1/dppsByProductId/{productId}, ett GTIN med 8 till 14 siffror eller en adress enligt GS1 Digital Link
ReadDPPIdsByProductIds (4.5)POST /api/v1/dppsByProductIds med {"productIds": ["09506000134352"]}, högst 1 000 GTIN
ReadDPPVersionByIdAndDate (4.4)GET /api/v1/dppsByIdAndDate/{dppId}?date=2026-11-14T12:00:00Z

Ett läsanrop svarar med den senaste versionen, eller för ett datum med den version som gällde då. Begär application/json, application/ld+json eller text/html i headern Accept (innehållsförhandling enligt EN 18216). Varje svar anger att det är säkerhetskopian, vilken version det är och SHA-256-hashen av innehållet.

Passets egen adress fungerar också: /01/{gtin} med nycklarna i GS1 Digital Link efter.

Läsanropen svarar på en domän som är öppen för läsning. En domän öppnas när ett varumärke pekar sin passdomän mot kopian. Överallt annars svarar ett läsanrop 404.

Erbjuds inte: ReadDataElement och UpdateDataElement (EN 18222 avsnitt 6).

Kvitton

Varje lagrad version får ett kvitto. Det består av två delar förenade med en punkt, var och en i base64url utan utfyllnad:

base64url(receipt as JSON) "." base64url(Ed25519 signature over the first part, as written)

Signaturen täcker den första delen exakt som den är skriven, så ingenting behöver sorteras före kontrollen. JSON-delen innehåller:

FältVad det är
vFormatversionen, nu 1
key_idNyckeln som signerade det
receipt_idId för den lagrade versionen
senderVem som skickade versionen
dpp_idPassets digitalProductPassportId
version_numberVersionens nummer, från 1
content_sha256SHA-256-hashen av innehållet, som hex
received_atNär versionen lagrades

Den publika nyckeln

GET /.well-known/backup-receipt-key svarar:

{
  "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 är de första 16 hexsiffrorna i SHA-256-hashen av nyckeln i SPKI-form. Kontrollera ett kvitto på verifieringssidan eller med valfritt Ed25519-bibliotek.

Felkoder

En avvisad skapelse eller uppdatering svarar 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 (skapa och uppdatera)
400Innehållet är inte ett JSON-objekt, ett obligatoriskt attribut saknas eller är fel, passet är ett utkast, id:t har ändrats, eller Idempotency-Key är ogiltig eller har använts med en annan begäran.
401Åtkomstnyckeln är fel eller saknas.
403Anslutningen gäller inte längre.
404En uppdatering av ett pass som inte förvaras för den här anslutningen.
405En borttagning, eller en metod som inte är tillåten på sökvägen.
409En skapelse av ett pass som redan förvaras, en uppdatering som krockade med en annan uppdatering, eller ett anrop vars Idempotency-Key fortfarande körs (med Retry-After).
413Innehållet, eller passet efter uppdateringen, är större än 1 048 576 byte.
429För många anrop. Vänta det antal sekunder som anges i Retry-After.
500Passet kunde inte lagras. Skicka det igen; med samma Idempotency-Key lagras ingenting två gånger.

Läsanropen svarar {"error": "…"}:

StatusNär (läsning)
300Mer än ett varumärke har ett pass på den här adressen. Svaret listar dem.
400Id:t, GTIN eller datumet saknas eller är ogiltigt.
404Passet förvaras inte i kopian, eller domänen är inte öppen för läsning.
405En metod som inte är tillåten på sökvägen.
413Fler än 1 000 produkt-id:n.
429För många förfrågningar. Vänta det antal sekunder som anges i Retry-After.
503Tillfälligt otillgänglig. Försök igen efter Retry-After.

Ha en säkerhetskopia av dina pass

Skapa en organisation med din e-postadress på företaget. När den är godkänd ansluter du plattformen som har dina pass.

Du behöver en e-postadress på företaget. Vår personal granskar nya organisationer på vardagar. Portalen är på engelska.