Dokumentation für Passplattformen
dpp-backup.com bietet die Lebenszyklus-Aufrufe von EN 18222 an. Eine Plattform sendet Pässe mit CreateDPP und UpdateDPPById, und vier Leseaufrufe antworten aus der Kopie. Jede gespeicherte Version kommt mit einer Empfangsbestätigung zurück, die mit Ed25519 signiert ist.
Die Grundlagen
- Adresse:
https://dpp-backup.com/api/v1 - Zugangsschlüssel:
Authorization: Bearer <credential>. Die Marke legt die Verbindung in ihrem Portal an und gibt Ihnen den Zugangsschlüssel. Er führt zur Kopie dieser Marke und nirgendwohin sonst. - Body: JSON, höchstens 1.048.576 Bytes.
- Pfade: wie in EN 18222 Tabelle 16. Kodieren Sie eine ID im Pfad mit Prozentkodierung.
Pässe senden
| EN-18222-Aufruf | Anfrage | Antwort |
|---|---|---|
| CreateDPP (4.6) | POST /api/v1/dpps mit dem vollständigen Pass | 201 und die gespeicherte Version |
| UpdateDPPById (4.7) | PATCH /api/v1/dpps/{dppId} mit den geänderten Teilen | 200 und der Pass, wie er gespeichert ist |
| DeleteDPPById (4.8) | DELETE /api/v1/dpps/{dppId} | Immer 405. Eine Sicherungskopie wird für die Lebensdauer des Passes aufbewahrt. |
Eine Aktualisierung ist ein JSON Merge Patch (RFC 7396), wie EN 18222 8.1 es vorschlägt. Ein null entfernt ein Element. Der Patch wird mit der neuesten gespeicherten Version zusammengeführt, und das Ergebnis wird als nächste Version gespeichert. Ist der zusammengeführte Pass nicht gültig, wird nichts gespeichert.
Was ein Pass enthalten muss
Die Attribute aus EN 18223 Tabelle 1:
digitalProductPassportId: eine Zeichenkette mit höchstens 500 Zeichen. Sie kann bei einer Aktualisierung nicht geändert werden.uniqueProductIdentifier: zum Beispiel eine Adresse nach GS1 Digital Link.granularity:model,batchoderitem.dppSchemaVersiondppStatus:active,inactive,archivedoderinvalid. Gesichert werden nur veröffentlichte Pässe, ein Entwurf wird daher abgewiesen.lastUpdated: ISO 8601 mit Zeitzone, zum Beispiel2026-11-16T09:00:00Z. Der Wert wird aufbewahrt, maßgeblich für eine Version ist aber der Zeitpunkt ihrer Speicherung.economicOperatorId- Falls angegeben:
facilityId(eine Zeichenkette) undcontentSpecificationIds(eine Liste von Zeichenketten).
Alles andere im Pass ist ein Datenelement und wird so gespeichert, wie es gesendet wurde.
Was nicht öffentlich ist
EN 18222 enthält keine eigenen Zugriffsregeln. Daher führen Sie die nicht öffentlichen Datenelemente in einem zusätzlichen Element auf, x-backup. Es ist kein Datenelement und wird nie veröffentlicht.
"x-backup": { "withheldFromPublic": ["supplierPrice", "factoryAudit"] }
EN 18221 4.3 verlangt, dass die Kopie die Zugriffsbeschränkungen des ursprünglichen Passes beibehält, und aus dieser Liste kennt die Kopie sie. Ohne sie zeigen wir öffentlich keine Produktdaten dieser Version, statt zu raten. Bei einer Aktualisierung bleibt ein Element, das Sie weglassen, unverändert.
Angehängte Dokumente (EN 18221 4.4): Wie ihre Dateien gesendet werden, ist hier noch nicht beschrieben. Demnächst
Einen Aufruf erneut senden
Ein Anlegen oder eine Aktualisierung kann einen Idempotency-Key-Header mit 1 bis 200 druckbaren Zeichen tragen. Derselbe Schlüssel mit derselben Anfrage erhält erneut die erste Antwort, mit Idempotent-Replay: true, und es wird nichts Neues gespeichert. Derselbe Schlüssel mit einer anderen Anfrage wird abgewiesen.
Ein Beispiel
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..."
}
}
Aus der Kopie lesen
| EN-18222-Aufruf | Anfrage |
|---|---|
| ReadDPPById (4.2) | GET /api/v1/dpps/{dppId} |
| ReadDPPByProductId (4.3) | GET /api/v1/dppsByProductId/{productId}, eine GTIN mit 8 bis 14 Ziffern oder eine Adresse nach GS1 Digital Link |
| ReadDPPIdsByProductIds (4.5) | POST /api/v1/dppsByProductIds mit {"productIds": ["09506000134352"]}, höchstens 1.000 GTINs |
| ReadDPPVersionByIdAndDate (4.4) | GET /api/v1/dppsByIdAndDate/{dppId}?date=2026-11-14T12:00:00Z |
Ein Leseaufruf liefert die neueste Version oder, für ein Datum, die damals gültige Version. Fordern Sie im Accept-Header application/json, application/ld+json oder text/html an (Content Negotiation nach EN 18216). Jede Antwort gibt an, dass es sich um die Sicherungskopie handelt, um welche Version es geht und welchen SHA-256-Hash ihr Inhalt hat.
Auch die eigene Adresse des Passes funktioniert: /01/{gtin} mit den GS1 Digital Link-Schlüsseln dahinter.
Die Leseaufrufe antworten auf einer Domain, die zum Lesen geöffnet ist. Eine Domain wird geöffnet, wenn eine Marke ihre Pass-Domain auf die Kopie umstellt. Überall sonst antwortet ein Leseaufruf mit 404.
Nicht angeboten: ReadDataElement und UpdateDataElement (EN 18222 Abschnitt 6).
Empfangsbestätigungen
Jede gespeicherte Version erhält eine Empfangsbestätigung. Sie besteht aus zwei Teilen, die durch einen Punkt verbunden sind, jeweils base64url ohne Auffüllung:
base64url(receipt as JSON) "." base64url(Ed25519 signature over the first part, as written)
Die Signatur deckt den ersten Teil genau so ab, wie er geschrieben ist. Vor der Prüfung muss daher nichts sortiert werden. Das JSON enthält:
| Feld | Bedeutung |
|---|---|
v | Die Formatversion, derzeit 1 |
key_id | Der Schlüssel, der signiert hat |
receipt_id | Die ID der gespeicherten Version |
sender | Wer die Version gesendet hat |
dpp_id | Die digitalProductPassportId |
version_number | Die Nummer der Version, ab 1 |
content_sha256 | Der SHA-256-Hash des Inhalts, hexadezimal |
received_at | Wann die Version gespeichert wurde |
Der öffentliche Schlüssel
GET /.well-known/backup-receipt-key antwortet:
{
"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 sind die ersten 16 Hexadezimalziffern des SHA-256-Hashes des Schlüssels in seiner SPKI-Form. Prüfen Sie eine Empfangsbestätigung auf der Prüfseite oder mit einer beliebigen Ed25519-Bibliothek.
Fehlercodes
Ein abgewiesenes Anlegen oder eine abgewiesene Aktualisierung antwortet mit dem Ergebnisobjekt aus 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 | Wann (Anlegen und Aktualisieren) |
|---|---|
| 400 | Der Body ist kein JSON-Objekt, ein Pflichtattribut fehlt oder ist falsch, der Pass ist ein Entwurf, die ID wurde geändert, oder der Idempotency-Key ist ungültig oder wurde mit einer anderen Anfrage verwendet. |
| 401 | Der Zugangsschlüssel ist falsch oder fehlt. |
| 403 | Die Verbindung ist nicht mehr gültig. |
| 404 | Eine Aktualisierung für einen Pass, der für diese Verbindung nicht gehalten wird. |
| 405 | Ein Löschen oder eine Methode, die auf dem Pfad nicht erlaubt ist. |
| 409 | Ein Anlegen für einen Pass, der bereits gehalten wird, eine Aktualisierung, die mit einer anderen Aktualisierung zusammengetroffen ist, oder ein Aufruf, dessen Idempotency-Key noch in Bearbeitung ist (mit Retry-After). |
| 413 | Der Body oder der Pass nach der Aktualisierung ist größer als 1.048.576 Bytes. |
| 429 | Zu viele Aufrufe. Warten Sie die Sekunden aus Retry-After ab. |
| 500 | Der Pass konnte nicht gespeichert werden. Senden Sie ihn erneut; mit demselben Idempotency-Key wird nichts doppelt gespeichert. |
Die Leseaufrufe antworten mit {"error": "…"}:
| Status | Wann (Leseaufrufe) |
|---|---|
| 300 | Mehr als eine Marke hält unter dieser Adresse einen Pass. Die Antwort führt sie auf. |
| 400 | Die ID, die GTIN oder das Datum fehlt oder ist ungültig. |
| 404 | Der Pass ist nicht in der Kopie vorhanden, oder die Domain ist nicht zum Lesen geöffnet. |
| 405 | Eine Methode, die auf dem Pfad nicht erlaubt ist. |
| 413 | Mehr als 1.000 Produktkennungen. |
| 429 | Zu viele Anfragen. Warten Sie die Sekunden aus Retry-After ab. |
| 503 | Vorübergehend nicht verfügbar. Versuchen Sie es nach Retry-After erneut. |
Halten Sie eine Sicherungskopie Ihrer Pässe bereit
Legen Sie mit Ihrer geschäftlichen E-Mail-Adresse eine Organisation an. Nach der Freigabe verbinden Sie die Plattform, die Ihre Pässe hält.
Eine geschäftliche E-Mail-Adresse ist erforderlich. Unsere Mitarbeiter prüfen neue Organisationen an Werktagen. Das Portal ist auf Englisch.