Dokumentacja dla platform paszportów

dpp-backup.com udostępnia wywołania cyklu życia z EN 18222. Platforma przesyła paszporty za pomocą CreateDPP i UpdateDPPById, a cztery wywołania odczytu odpowiadają z kopii. Każda przechowywana wersja jest zwracana z potwierdzeniem podpisanym kluczem Ed25519.

Podstawy

  • Adres: https://dpp-backup.com/api/v1
  • Dane uwierzytelniające: Authorization: Bearer <credential>. Marka tworzy połączenie w swoim portalu i przekazuje Państwu dane uwierzytelniające. Prowadzą one do kopii tej marki i nigdzie indziej.
  • Treść: JSON, maksymalnie 1 048 576 bajtów.
  • Ścieżki: jak w tabeli 16 EN 18222. Identyfikator w ścieżce należy zakodować procentowo.

Przesyłanie paszportów

Wywołanie EN 18222ŻądanieOdpowiedź
CreateDPP (4.6)POST /api/v1/dpps z całym paszportem201 i przechowywana wersja
UpdateDPPById (4.7)PATCH /api/v1/dpps/{dppId} ze zmienionymi częściami200 i paszport w postaci przechowywanej
DeleteDPPById (4.8)DELETE /api/v1/dpps/{dppId}Zawsze 405. Kopia zapasowa jest przechowywana przez cały okres życia paszportu.

Aktualizacja to JSON merge patch (RFC 7396), zgodnie z sugestią EN 18222 8.1. Wartość null usuwa element. Łatka jest scalana z najnowszą przechowywaną wersją, a wynik zapisywany jest jako następna wersja. Jeśli scalony paszport jest nieprawidłowy, nic nie zostaje zapisane.

Co musi zawierać paszport

Atrybuty z tabeli 1 EN 18223:

  • digitalProductPassportId: ciąg znaków o długości maksymalnie 500 znaków. Nie może zmienić się w aktualizacji.
  • uniqueProductIdentifier: na przykład adres GS1 Digital Link.
  • granularity: model, batch lub item.
  • dppSchemaVersion
  • dppStatus: active, inactive, archived lub invalid. Kopia zapasowa obejmuje tylko opublikowane paszporty, więc wersja robocza jest odrzucana.
  • lastUpdated: ISO 8601 ze strefą czasową, na przykład 2026-11-16T09:00:00Z. Wartość jest zachowywana, ale czasem wersji jest czas jej zapisania.
  • economicOperatorId
  • Jeśli podano: facilityId (ciąg znaków) i contentSpecificationIds (lista ciągów znaków).

Wszystko inne w paszporcie jest elementem danych i jest przechowywane w postaci, w jakiej zostało przesłane.

Co nie jest publiczne

EN 18222 nie zawiera własnych reguł dostępu, dlatego elementy danych, które nie są publiczne, wymienia się w jednym dodatkowym elemencie, x-backup. Nie jest on elementem danych i nigdy nie jest publikowany.

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

EN 18221 4.3 wymaga, aby kopia zachowała ograniczenia dostępu oryginalnego paszportu, a ta lista jest sposobem, w jaki kopia je zna. Bez niej nie pokazujemy publicznie żadnych danych produktu z tej wersji, zamiast zgadywać. W aktualizacji pominięty element pozostaje bez zmian.

Załączone dokumenty (EN 18221 4.4): sposób przesyłania ich plików nie jest tu jeszcze opisany. Wkrótce

Ponowne wysłanie wywołania

Tworzenie lub aktualizacja może zawierać nagłówek Idempotency-Key o długości od 1 do 200 drukowalnych znaków. Ten sam klucz z tym samym żądaniem otrzymuje ponownie pierwszą odpowiedź, z Idempotent-Replay: true, i nic nowego nie zostaje zapisane. Ten sam klucz z innym żądaniem jest odrzucany.

Przykład

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

Odczyt z kopii

Wywołanie EN 18222Żądanie
ReadDPPById (4.2)GET /api/v1/dpps/{dppId}
ReadDPPByProductId (4.3)GET /api/v1/dppsByProductId/{productId}, GTIN o długości od 8 do 14 cyfr lub adres GS1 Digital Link
ReadDPPIdsByProductIds (4.5)POST /api/v1/dppsByProductIds z {"productIds": ["09506000134352"]}, maksymalnie 1000 numerów GTIN
ReadDPPVersionByIdAndDate (4.4)GET /api/v1/dppsByIdAndDate/{dppId}?date=2026-11-14T12:00:00Z

Odczyt zwraca najnowszą wersję lub, dla podanej daty, wersję aktualną w tym czasie. W nagłówku Accept należy zażądać application/json, application/ld+json lub text/html (negocjacja treści według EN 18216). Każda odpowiedź wskazuje, że jest kopią zapasową, którą wersją jest, oraz skrót SHA-256 jej treści.

Działa także własny adres paszportu: /01/{gtin} z następującymi po nim kluczami GS1 Digital Link.

Wywołania odczytu odpowiadają w domenie otwartej do odczytu. Domena zostaje otwarta, gdy marka skieruje swoją domenę paszportów na kopię. W pozostałych przypadkach odczyt zwraca 404.

Nieudostępniane: ReadDataElement i UpdateDataElement (EN 18222, punkt 6).

Potwierdzenia

Każda przechowywana wersja otrzymuje potwierdzenie. Składa się ono z dwóch części połączonych kropką, każda w base64url bez dopełnienia:

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

Podpis obejmuje pierwszą część dokładnie w zapisanej postaci, więc przed sprawdzeniem niczego nie trzeba porządkować. JSON zawiera:

PoleCo to jest
vWersja formatu, obecnie 1
key_idKlucz, którym podpisano potwierdzenie
receipt_idIdentyfikator przechowywanej wersji
senderKto przesłał wersję
dpp_iddigitalProductPassportId
version_numberNumer wersji, od 1
content_sha256Skrót SHA-256 treści, szesnastkowo
received_atKiedy wersja została zapisana

Klucz publiczny

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

{
  "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 to pierwsze 16 cyfr szesnastkowych skrótu SHA-256 klucza w postaci SPKI. Potwierdzenie można sprawdzić na stronie weryfikacji lub za pomocą dowolnej biblioteki Ed25519.

Kody błędów

Odrzucone tworzenie lub aktualizacja zwraca obiekt wyniku z 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"
    }
  ]
}
StatusKiedy (tworzenie i aktualizacja)
400Treść nie jest obiektem JSON, brakuje obowiązkowego atrybutu lub jest on błędny, paszport jest wersją roboczą, identyfikator został zmieniony albo Idempotency-Key jest nieprawidłowy lub został użyty z innym żądaniem.
401Dane uwierzytelniające są błędne lub ich brak.
403Połączenie nie jest już aktywne.
404Aktualizacja paszportu, który nie jest przechowywany dla tego połączenia.
405Usunięcie lub metoda niedozwolona dla tej ścieżki.
409Tworzenie paszportu, który jest już przechowywany, aktualizacja, która zbiegła się z inną aktualizacją, lub wywołanie, którego Idempotency-Key jest nadal w trakcie przetwarzania (z Retry-After).
413Treść lub paszport po aktualizacji przekracza 1 048 576 bajtów.
429Zbyt wiele wywołań. Proszę odczekać liczbę sekund podaną w Retry-After.
500Nie udało się zapisać paszportu. Proszę wysłać go ponownie; przy tym samym Idempotency-Key nic nie zostanie zapisane dwukrotnie.

Wywołania odczytu zwracają {"error": "…"}:

StatusKiedy (odczyty)
300Pod tym adresem paszport ma więcej niż jedna marka. Odpowiedź wymienia je wszystkie.
400Brakuje identyfikatora, numeru GTIN lub daty albo są one nieprawidłowe.
404Paszport nie jest przechowywany w kopii albo domena nie jest otwarta do odczytu.
405Metoda niedozwolona dla tej ścieżki.
413Ponad 1000 identyfikatorów produktów.
429Zbyt wiele żądań. Proszę odczekać liczbę sekund podaną w Retry-After.
503Usługa chwilowo niedostępna. Proszę spróbować ponownie po czasie podanym w Retry-After.

Przechowuj kopię zapasową swoich paszportów

Utwórz organizację, używając firmowego adresu e-mail. Po jej zatwierdzeniu podłączają Państwo platformę, w której znajdują się paszporty.

Wymagany jest firmowy adres e-mail. Nowe organizacje sprawdzają nasi pracownicy w dni robocze. Portal jest w języku angielskim.