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-aanroep | Verzoek | Antwoord |
|---|---|---|
| CreateDPP (4.6) | POST /api/v1/dpps met het hele paspoort | 201 en de opgeslagen versie |
| UpdateDPPById (4.7) | PATCH /api/v1/dpps/{dppId} met de delen die zijn gewijzigd | 200 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,batchofitem.dppSchemaVersiondppStatus:active,inactive,archivedofinvalid. Alleen gepubliceerde paspoorten worden geback-upt, dus een concept wordt geweigerd.lastUpdated: ISO 8601 met een tijdzone, bijvoorbeeld2026-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) encontentSpecificationIds(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-aanroep | Verzoek |
|---|---|
| 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:
| Veld | Wat het is |
|---|---|
v | De formaatversie, nu 1 |
key_id | De sleutel die het heeft ondertekend |
receipt_id | De id van de opgeslagen versie |
sender | Wie de versie heeft verstuurd |
dpp_id | De digitalProductPassportId |
version_number | Het nummer van de versie, vanaf 1 |
content_sha256 | De SHA-256-hash van de inhoud, als hex |
received_at | Wanneer 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"
}
]
}
| Status | Wanneer (aanmaken en bijwerken) |
|---|---|
| 400 | De 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. |
| 401 | De toegangssleutel is onjuist of ontbreekt. |
| 403 | De koppeling is niet meer van kracht. |
| 404 | Een update voor een paspoort dat niet voor deze koppeling wordt bewaard. |
| 405 | Een verwijdering, of een methode die op het pad niet is toegestaan. |
| 409 | Een 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). |
| 413 | De body, of het paspoort na de update, is groter dan 1.048.576 bytes. |
| 429 | Te veel aanroepen. Wacht het aantal seconden in Retry-After. |
| 500 | Het paspoort kon niet worden opgeslagen. Verstuur het opnieuw; met dezelfde Idempotency-Key wordt niets twee keer opgeslagen. |
De leesaanroepen antwoorden met {"error": "…"}:
| Status | Wanneer (lezen) |
|---|---|
| 300 | Meer dan één merk bewaart een paspoort op dit adres. Het antwoord somt ze op. |
| 400 | De id, het GTIN of de datum ontbreekt of is ongeldig. |
| 404 | Het paspoort wordt niet in de kopie bewaard, of het domein is niet open voor lezen. |
| 405 | Een methode die op het pad niet is toegestaan. |
| 413 | Meer dan 1.000 product-id's. |
| 429 | Te veel verzoeken. Wacht het aantal seconden in Retry-After. |
| 503 | Tijdelijk 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.