Dokumentaatio passialustoille
dpp-backup.com tarjoaa EN 18222 -standardin elinkaarikutsut. Alusta lähettää passit kutsuilla CreateDPP ja UpdateDPPById, ja neljä lukukutsua vastaa kopiosta. Jokainen tallennettu versio palautetaan Ed25519-algoritmilla allekirjoitetun kuitin kanssa.
Perusteet
- Osoite:
https://dpp-backup.com/api/v1 - Tunnistetieto:
Authorization: Bearer <credential>. Tuotemerkki luo yhteyden portaalissaan ja antaa sinulle tunnistetiedon. Se johtaa kyseisen tuotemerkin kopioon eikä minnekään muualle. - Runko: JSON, enintään 1 048 576 tavua.
- Polut: kuten EN 18222 -standardin taulukossa 16. Prosenttikoodaa polussa oleva tunniste.
Passien lähettäminen
| EN 18222 -kutsu | Pyyntö | Vastaus |
|---|---|---|
| CreateDPP (4.6) | POST /api/v1/dpps koko passin kanssa | 201 ja tallennettu versio |
| UpdateDPPById (4.7) | PATCH /api/v1/dpps/{dppId} muuttuneiden osien kanssa | 200 ja passi tallennetussa muodossa |
| DeleteDPPById (4.8) | DELETE /api/v1/dpps/{dppId} | Aina 405. Varmuuskopio säilytetään passin koko elinkaaren ajan. |
Päivitys on JSON merge patch (RFC 7396), kuten EN 18222 -standardin kohta 8.1 ehdottaa. null poistaa jäsenen. Korjaus yhdistetään uusimpaan tallennettuun versioon, ja tulos tallennetaan seuraavana versiona. Jos yhdistetty passi ei ole kelvollinen, mitään ei tallenneta.
Mitä passissa on oltava
EN 18223 -standardin taulukon 1 attribuutit:
digitalProductPassportId: merkkijono, jossa on enintään 500 merkkiä. Sitä ei voi muuttaa päivityksessä.uniqueProductIdentifier: esimerkiksi GS1 Digital Link -osoite.granularity:model,batchtaiitem.dppSchemaVersiondppStatus:active,inactive,archivedtaiinvalid. Vain julkaistuista passeista tehdään varmuuskopio, joten luonnos hylätään.lastUpdated: ISO 8601 aikavyöhykkeen kanssa, esimerkiksi2026-11-16T09:00:00Z. Se säilytetään, mutta version aika on sen tallennusaika.economicOperatorId- Jos annettu:
facilityId(merkkijono) jacontentSpecificationIds(merkkijonojen luettelo).
Kaikki muu passissa on tietoelementtejä, ja ne tallennetaan sellaisinaan.
Mikä ei ole julkista
EN 18222 ei sisällä omia käyttöoikeussääntöjä, joten luettelet ei-julkiset tietoelementit yhdessä lisäjäsenessä, x-backup. Se ei ole tietoelementti, eikä sitä koskaan julkaista.
"x-backup": { "withheldFromPublic": ["supplierPrice", "factoryAudit"] }
EN 18221 -standardin kohta 4.3 edellyttää, että kopio säilyttää alkuperäisen passin käyttörajoitukset, ja tästä luettelosta kopio tietää ne. Ilman sitä emme näytä version tuotetietoja julkisesti lainkaan arvaamisen sijaan. Päivityksessä jäsen, jonka jätät pois, pysyy ennallaan.
Liitetyt asiakirjat (EN 18221, kohta 4.4): niiden tiedostojen lähettämistä ei ole vielä kuvattu tässä. Tulossa
Kutsun lähettäminen uudelleen
Luonti- tai päivityskutsussa voi olla Idempotency-Key-otsake, jossa on 1–200 tulostettavaa merkkiä. Sama avain samalla pyynnöllä palauttaa ensimmäisen vastauksen uudelleen otsakkeella Idempotent-Replay: true, eikä mitään uutta tallenneta. Sama avain toisella pyynnöllä hylätään.
Esimerkki
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..."
}
}
Lukeminen kopiosta
| EN 18222 -kutsu | Pyyntö |
|---|---|
| ReadDPPById (4.2) | GET /api/v1/dpps/{dppId} |
| ReadDPPByProductId (4.3) | GET /api/v1/dppsByProductId/{productId}, 8–14-numeroinen GTIN tai GS1 Digital Link -osoite |
| ReadDPPIdsByProductIds (4.5) | POST /api/v1/dppsByProductIds sisällöllä {"productIds": ["09506000134352"]}, enintään 1 000 GTIN-koodia |
| ReadDPPVersionByIdAndDate (4.4) | GET /api/v1/dppsByIdAndDate/{dppId}?date=2026-11-14T12:00:00Z |
Lukukutsu palauttaa uusimman version tai, jos päivämäärä annetaan, silloin voimassa olleen version. Pyydä Accept-otsakkeessa application/json, application/ld+json tai text/html (EN 18216 -standardin sisältöneuvottelu). Jokainen vastaus kertoo, että se on varmuuskopio, mikä versio se on ja sen sisällön SHA-256-tiivisteen.
Myös passin oma osoite toimii: /01/{gtin} ja sen perässä GS1 Digital Link -avaimet.
Lukukutsut vastaavat verkkotunnuksessa, joka on avattu lukemista varten. Verkkotunnus avataan, kun tuotemerkki ohjaa passiensa verkkotunnuksen kopioon. Kaikkialla muualla lukukutsu vastaa 404.
Ei tarjolla: ReadDataElement ja UpdateDataElement (EN 18222, kohta 6).
Kuitit
Jokainen tallennettu versio saa kuitin. Se koostuu kahdesta pisteellä yhdistetystä osasta, kumpikin base64url-muodossa ilman täytettä:
base64url(receipt as JSON) "." base64url(Ed25519 signature over the first part, as written)
Allekirjoitus kattaa ensimmäisen osan täsmälleen kirjoitetussa muodossa, joten mitään ei tarvitse järjestää ennen tarkistusta. JSON sisältää:
| Kenttä | Mitä se on |
|---|---|
v | Muodon versio, nyt 1 |
key_id | Avain, joka allekirjoitti sen |
receipt_id | Tallennetun version tunniste |
sender | Kuka version lähetti |
dpp_id | digitalProductPassportId |
version_number | Version numero, alkaen 1:stä |
content_sha256 | Sisällön SHA-256-tiiviste heksadesimaalimuodossa |
received_at | Milloin versio tallennettiin |
Julkinen avain
GET /.well-known/backup-receipt-key vastaa:
{
"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 on avaimen SPKI-muodon SHA-256-tiivisteen 16 ensimmäistä heksadesimaalinumeroa. Tarkista kuitti tarkistussivulla tai millä tahansa Ed25519-kirjastolla.
Virhekoodit
Hylätty luonti tai päivitys vastaa EN 18222 -standardin kohdan 7.2 tulosobjektilla:
{
"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"
}
]
}
| Tila | Milloin (luonti ja päivitys) |
|---|---|
| 400 | Runko ei ole JSON-objekti, pakollinen attribuutti puuttuu tai on virheellinen, passi on luonnos, tunnistetta on muutettu tai Idempotency-Key ei ole kelvollinen tai sitä on käytetty toisessa pyynnössä. |
| 401 | Tunnistetieto on väärä tai puuttuu. |
| 403 | Yhteys ei ole enää voimassa. |
| 404 | Päivitys passiin, jota ei säilytetä tälle yhteydelle. |
| 405 | Poisto tai menetelmä, joka ei ole sallittu polulla. |
| 409 | Luonti passille, joka on jo säilytyksessä, päivitys, joka osui yhteen toisen päivityksen kanssa, tai kutsu, jonka Idempotency-Key on yhä käsittelyssä (otsakkeella Retry-After). |
| 413 | Runko tai passi päivityksen jälkeen on suurempi kuin 1 048 576 tavua. |
| 429 | Liian monta kutsua. Odota Retry-After-otsakkeen ilmoittama määrä sekunteja. |
| 500 | Passia ei voitu tallentaa. Lähetä se uudelleen; samalla Idempotency-Key-avaimella mitään ei tallenneta kahdesti. |
Lukukutsut vastaavat {"error": "…"}:
| Tila | Milloin (lukukutsut) |
|---|---|
| 300 | Useampi kuin yksi tuotemerkki säilyttää passia tässä osoitteessa. Vastaus luettelee ne. |
| 400 | Tunniste, GTIN tai päivämäärä puuttuu tai ei ole kelvollinen. |
| 404 | Passia ei säilytetä kopiossa, tai verkkotunnusta ei ole avattu lukemista varten. |
| 405 | Menetelmä, joka ei ole sallittu polulla. |
| 413 | Yli 1 000 tuotetunnistetta. |
| 429 | Liian monta pyyntöä. Odota Retry-After-otsakkeen ilmoittama määrä sekunteja. |
| 503 | Tilapäisesti poissa käytöstä. Yritä uudelleen Retry-After-ajan jälkeen. |
Säilytä passiesi varmuuskopio
Luo organisaatio yrityksesi sähköpostiosoitteella. Kun se on hyväksytty, yhdistät alustan, jossa passisi ovat.
Tarvitset yrityksen sähköpostiosoitteen. Henkilökuntamme käsittelee uudet organisaatiot arkipäivisin. Portaali on englanninkielinen.