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 | Żądanie | Odpowiedź |
|---|---|---|
| CreateDPP (4.6) | POST /api/v1/dpps z całym paszportem | 201 i przechowywana wersja |
| UpdateDPPById (4.7) | PATCH /api/v1/dpps/{dppId} ze zmienionymi częściami | 200 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,batchlubitem.dppSchemaVersiondppStatus:active,inactive,archivedlubinvalid. Kopia zapasowa obejmuje tylko opublikowane paszporty, więc wersja robocza jest odrzucana.lastUpdated: ISO 8601 ze strefą czasową, na przykład2026-11-16T09:00:00Z. Wartość jest zachowywana, ale czasem wersji jest czas jej zapisania.economicOperatorId- Jeśli podano:
facilityId(ciąg znaków) icontentSpecificationIds(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:
| Pole | Co to jest |
|---|---|
v | Wersja formatu, obecnie 1 |
key_id | Klucz, którym podpisano potwierdzenie |
receipt_id | Identyfikator przechowywanej wersji |
sender | Kto przesłał wersję |
dpp_id | digitalProductPassportId |
version_number | Numer wersji, od 1 |
content_sha256 | Skrót SHA-256 treści, szesnastkowo |
received_at | Kiedy 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"
}
]
}
| Status | Kiedy (tworzenie i aktualizacja) |
|---|---|
| 400 | Treść 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. |
| 401 | Dane uwierzytelniające są błędne lub ich brak. |
| 403 | Połączenie nie jest już aktywne. |
| 404 | Aktualizacja paszportu, który nie jest przechowywany dla tego połączenia. |
| 405 | Usunięcie lub metoda niedozwolona dla tej ścieżki. |
| 409 | Tworzenie 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). |
| 413 | Treść lub paszport po aktualizacji przekracza 1 048 576 bajtów. |
| 429 | Zbyt wiele wywołań. Proszę odczekać liczbę sekund podaną w Retry-After. |
| 500 | Nie 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": "…"}:
| Status | Kiedy (odczyty) |
|---|---|
| 300 | Pod tym adresem paszport ma więcej niż jedna marka. Odpowiedź wymienia je wszystkie. |
| 400 | Brakuje identyfikatora, numeru GTIN lub daty albo są one nieprawidłowe. |
| 404 | Paszport nie jest przechowywany w kopii albo domena nie jest otwarta do odczytu. |
| 405 | Metoda niedozwolona dla tej ścieżki. |
| 413 | Ponad 1000 identyfikatorów produktów. |
| 429 | Zbyt wiele żądań. Proszę odczekać liczbę sekund podaną w Retry-After. |
| 503 | Usł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.