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 -kutsuPyyntöVastaus
CreateDPP (4.6)POST /api/v1/dpps koko passin kanssa201 ja tallennettu versio
UpdateDPPById (4.7)PATCH /api/v1/dpps/{dppId} muuttuneiden osien kanssa200 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, batch tai item.
  • dppSchemaVersion
  • dppStatus: active, inactive, archived tai invalid. Vain julkaistuista passeista tehdään varmuuskopio, joten luonnos hylätään.
  • lastUpdated: ISO 8601 aikavyöhykkeen kanssa, esimerkiksi 2026-11-16T09:00:00Z. Se säilytetään, mutta version aika on sen tallennusaika.
  • economicOperatorId
  • Jos annettu: facilityId (merkkijono) ja contentSpecificationIds (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 -kutsuPyyntö
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
vMuodon versio, nyt 1
key_idAvain, joka allekirjoitti sen
receipt_idTallennetun version tunniste
senderKuka version lähetti
dpp_iddigitalProductPassportId
version_numberVersion numero, alkaen 1:stä
content_sha256Sisällön SHA-256-tiiviste heksadesimaalimuodossa
received_atMilloin 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"
    }
  ]
}
TilaMilloin (luonti ja päivitys)
400Runko 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ä.
401Tunnistetieto on väärä tai puuttuu.
403Yhteys ei ole enää voimassa.
404Päivitys passiin, jota ei säilytetä tälle yhteydelle.
405Poisto tai menetelmä, joka ei ole sallittu polulla.
409Luonti 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).
413Runko tai passi päivityksen jälkeen on suurempi kuin 1 048 576 tavua.
429Liian monta kutsua. Odota Retry-After-otsakkeen ilmoittama määrä sekunteja.
500Passia ei voitu tallentaa. Lähetä se uudelleen; samalla Idempotency-Key-avaimella mitään ei tallenneta kahdesti.

Lukukutsut vastaavat {"error": "…"}:

TilaMilloin (lukukutsut)
300Useampi kuin yksi tuotemerkki säilyttää passia tässä osoitteessa. Vastaus luettelee ne.
400Tunniste, GTIN tai päivämäärä puuttuu tai ei ole kelvollinen.
404Passia ei säilytetä kopiossa, tai verkkotunnusta ei ole avattu lukemista varten.
405Menetelmä, joka ei ole sallittu polulla.
413Yli 1 000 tuotetunnistetta.
429Liian monta pyyntöä. Odota Retry-After-otsakkeen ilmoittama määrä sekunteja.
503Tilapä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.