Documentatie voor paspoortplatforms

dpp-backup.com biedt de levenscyclusaanroepen van EN 18222. Een platform stuurt paspoorten met CreateDPP en UpdateDPPById, en vier leesaanroepen antwoorden vanuit de kopie. Elke opgeslagen versie komt terug met een ontvangstbewijs dat met Ed25519 is ondertekend.

De basis

  • Adres: https://dpp-backup.com/api/v1
  • Toegangssleutel: Authorization: Bearer <credential>. Het merk maakt de koppeling aan in zijn portaal en geeft u de toegangssleutel. Die leidt naar de kopie van dat merk en nergens anders.
  • Body: JSON, ten hoogste 1.048.576 bytes.
  • Paden: zoals in EN 18222, tabel 16. Codeer een id in het pad met procentcodering.

Paspoorten versturen

EN 18222-aanroepVerzoekAntwoord
CreateDPP (4.6)POST /api/v1/dpps met het hele paspoort201 en de opgeslagen versie
UpdateDPPById (4.7)PATCH /api/v1/dpps/{dppId} met de delen die zijn gewijzigd200 en het paspoort zoals opgeslagen
DeleteDPPById (4.8)DELETE /api/v1/dpps/{dppId}Altijd 405. Een back-upkopie wordt bewaard voor de hele levensduur van het paspoort.

Een update is een JSON merge patch (RFC 7396), zoals EN 18222 8.1 voorstelt. Een null verwijdert een member. De patch wordt samengevoegd met de nieuwste opgeslagen versie, en het resultaat wordt opgeslagen als de volgende versie. Als het samengevoegde paspoort niet geldig is, wordt er niets opgeslagen.

Wat een paspoort moet bevatten

De attributen van EN 18223, tabel 1:

  • digitalProductPassportId: een string van ten hoogste 500 tekens. Deze kan bij een update niet veranderen.
  • uniqueProductIdentifier: bijvoorbeeld een GS1 Digital Link-adres.
  • granularity: model, batch of item.
  • dppSchemaVersion
  • dppStatus: active, inactive, archived of invalid. Alleen gepubliceerde paspoorten worden geback-upt, dus een concept wordt geweigerd.
  • lastUpdated: ISO 8601 met een tijdzone, bijvoorbeeld 2026-11-16T09:00:00Z. Dit wordt bewaard, maar het tijdstip van een versie is het tijdstip waarop die is opgeslagen.
  • economicOperatorId
  • Indien opgegeven: facilityId (een string) en contentSpecificationIds (een lijst van strings).

Al het andere in het paspoort is een gegevenselement en wordt opgeslagen zoals verstuurd.

Wat niet openbaar is

EN 18222 kent zelf geen toegangsregels, dus u vermeldt de gegevenselementen die niet openbaar zijn in één extra member, x-backup. Dat is geen gegevenselement en wordt nooit gepubliceerd.

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

EN 18221 4.3 vraagt dat de kopie de toegangsbeperkingen van het oorspronkelijke paspoort behoudt, en via deze lijst kent de kopie ze. Zonder de lijst tonen we van die versie geen productinformatie openbaar, in plaats van te gokken. Bij een update blijft een member die u weglaat, zoals hij was.

Bijgevoegde documenten (EN 18221 4.4): hoe u de bestanden ervan verstuurt, wordt hier nog niet beschreven. Binnenkort

Een aanroep opnieuw versturen

Een aanmaak- of updateaanroep kan een Idempotency-Key-header bevatten van 1 tot 200 afdrukbare tekens. Dezelfde sleutel met hetzelfde verzoek krijgt opnieuw het eerste antwoord, met Idempotent-Replay: true, en er wordt niets nieuws opgeslagen. Dezelfde sleutel met een ander verzoek wordt geweigerd.

Een voorbeeld

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..."
  }
}

Lezen uit de kopie

EN 18222-aanroepVerzoek
ReadDPPById (4.2)GET /api/v1/dpps/{dppId}
ReadDPPByProductId (4.3)GET /api/v1/dppsByProductId/{productId}, een GTIN van 8 tot 14 cijfers of een GS1 Digital Link-adres
ReadDPPIdsByProductIds (4.5)POST /api/v1/dppsByProductIds met {"productIds": ["09506000134352"]}, ten hoogste 1.000 GTIN's
ReadDPPVersionByIdAndDate (4.4)GET /api/v1/dppsByIdAndDate/{dppId}?date=2026-11-14T12:00:00Z

Een leesaanroep geeft de nieuwste versie, of voor een datum de versie die toen gold. Vraag om application/json, application/ld+json of text/html in de Accept-header (contentonderhandeling volgens EN 18216). Elk antwoord vermeldt dat het de back-upkopie is, welke versie het is, en de SHA-256-hash van de inhoud.

Het eigen adres van het paspoort werkt ook: /01/{gtin} met de GS1 Digital Link-sleutels erachter.

De leesaanroepen antwoorden op een domein dat open is voor lezen. Een domein wordt geopend wanneer een merk zijn paspoortdomein naar de kopie laat verwijzen. Overal elders antwoordt een leesaanroep met 404.

Niet aangeboden: ReadDataElement en UpdateDataElement (EN 18222, clausule 6).

Ontvangstbewijzen

Elke opgeslagen versie krijgt een ontvangstbewijs. Het bestaat uit twee delen die met een punt zijn verbonden, elk in base64url zonder opvulling:

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

De handtekening dekt het eerste deel precies zoals het is geschreven, dus niets hoeft vóór de controle in volgorde te worden gezet. De JSON bevat:

VeldWat het is
vDe formaatversie, nu 1
key_idDe sleutel die het heeft ondertekend
receipt_idDe id van de opgeslagen versie
senderWie de versie heeft verstuurd
dpp_idDe digitalProductPassportId
version_numberHet nummer van de versie, vanaf 1
content_sha256De SHA-256-hash van de inhoud, als hex
received_atWanneer de versie is opgeslagen

De publieke sleutel

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

{
  "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 zijn de eerste 16 hexcijfers van de SHA-256-hash van de sleutel in SPKI-vorm. Controleer een ontvangstbewijs op de controlepagina, of met een willekeurige Ed25519-bibliotheek.

Foutcodes

Een geweigerde aanmaak- of updateaanroep antwoordt met het resultaatobject van 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"
    }
  ]
}
StatusWanneer (aanmaken en bijwerken)
400De body is geen JSON-object, een verplicht attribuut ontbreekt of is onjuist, het paspoort is een concept, de id is gewijzigd, of de Idempotency-Key is ongeldig of werd gebruikt met een ander verzoek.
401De toegangssleutel is onjuist of ontbreekt.
403De koppeling is niet meer van kracht.
404Een update voor een paspoort dat niet voor deze koppeling wordt bewaard.
405Een verwijdering, of een methode die op het pad niet is toegestaan.
409Een aanmaakaanroep voor een paspoort dat al wordt bewaard, een update die op een andere update stuitte, of een aanroep waarvan de Idempotency-Key nog loopt (met Retry-After).
413De body, of het paspoort na de update, is groter dan 1.048.576 bytes.
429Te veel aanroepen. Wacht het aantal seconden in Retry-After.
500Het paspoort kon niet worden opgeslagen. Verstuur het opnieuw; met dezelfde Idempotency-Key wordt niets twee keer opgeslagen.

De leesaanroepen antwoorden met {"error": "…"}:

StatusWanneer (lezen)
300Meer dan één merk bewaart een paspoort op dit adres. Het antwoord somt ze op.
400De id, het GTIN of de datum ontbreekt of is ongeldig.
404Het paspoort wordt niet in de kopie bewaard, of het domein is niet open voor lezen.
405Een methode die op het pad niet is toegestaan.
413Meer dan 1.000 product-id's.
429Te veel verzoeken. Wacht het aantal seconden in Retry-After.
503Tijdelijk niet beschikbaar. Probeer het opnieuw na Retry-After.

Bewaar een back-upkopie van uw paspoorten

Maak een organisatie aan met uw zakelijke e-mailadres. Zodra die is goedgekeurd, koppelt u het platform dat uw paspoorten beheert.

Een zakelijk e-mailadres is vereist. Onze medewerkers beoordelen nieuwe organisaties op werkdagen. Het portaal is in het Engels.