Documentation pour les plateformes de passeports
dpp-backup.com propose les appels de cycle de vie de l'EN 18222. Une plateforme envoie les passeports avec CreateDPP et UpdateDPPById, et quatre appels de lecture répondent à partir de la copie. Chaque version stockée est renvoyée avec un reçu signé avec Ed25519.
L'essentiel
- Adresse :
https://dpp-backup.com/api/v1 - Jeton d'accès :
Authorization: Bearer <credential>. La marque crée la connexion dans son portail et vous remet le jeton d'accès. Il mène à la copie de cette marque et nulle part ailleurs. - Corps : JSON, 1 048 576 octets au maximum.
- Chemins : comme dans le tableau 16 de l'EN 18222. Encodez en pourcentage un identifiant dans le chemin.
Envoyer des passeports
| Appel EN 18222 | Requête | Réponse |
|---|---|---|
| CreateDPP (4.6) | POST /api/v1/dpps avec le passeport complet | 201 et la version stockée |
| UpdateDPPById (4.7) | PATCH /api/v1/dpps/{dppId} avec les parties modifiées | 200 et le passeport tel qu'il est stocké |
| DeleteDPPById (4.8) | DELETE /api/v1/dpps/{dppId} | Toujours 405. Une copie de sauvegarde est conservée pendant toute la durée de vie du passeport. |
Une mise à jour est un JSON merge patch (RFC 7396), comme le suggère l'EN 18222 (8.1). Un null supprime un membre. Le patch est fusionné avec la version stockée la plus récente, et le résultat est stocké comme version suivante. Si le passeport fusionné n'est pas valide, rien n'est stocké.
Ce qu'un passeport doit contenir
Les attributs du tableau 1 de l'EN 18223 :
digitalProductPassportId: une chaîne de 500 caractères au maximum. Il ne peut pas changer lors d'une mise à jour.uniqueProductIdentifier: par exemple une adresse GS1 Digital Link.granularity:model,batchouitem.dppSchemaVersiondppStatus:active,inactive,archivedouinvalid. Seuls les passeports publiés sont sauvegardés, un brouillon est donc refusé.lastUpdated: ISO 8601 avec un fuseau horaire, par exemple2026-11-16T09:00:00Z. Il est conservé, mais l'heure d'une version est l'heure à laquelle elle a été stockée.economicOperatorId- S'ils sont fournis :
facilityId(une chaîne) etcontentSpecificationIds(une liste de chaînes).
Tout le reste du passeport est un élément de données et est stocké tel qu'il a été envoyé.
Ce qui n'est pas public
L'EN 18222 ne comporte pas de règles d'accès propres. Vous indiquez donc les éléments de données non publics dans un membre supplémentaire, x-backup. Ce n'est pas un élément de données et il n'est jamais publié.
"x-backup": { "withheldFromPublic": ["supplierPrice", "factoryAudit"] }
L'EN 18221 (4.3) demande que la copie conserve les restrictions d'accès du passeport d'origine, et c'est par cette liste que la copie les connaît. Sans elle, nous ne montrons publiquement aucune donnée produit de cette version plutôt que de deviner. Lors d'une mise à jour, un membre que vous omettez reste inchangé.
Documents joints (EN 18221, 4.4) : la manière d'envoyer leurs fichiers n'est pas encore décrite ici. Bientôt
Renvoyer un appel
Une création ou une mise à jour peut porter un en-tête Idempotency-Key de 1 à 200 caractères imprimables. La même clé avec la même requête renvoie la première réponse, avec Idempotent-Replay: true, et rien de nouveau n'est stocké. La même clé avec une autre requête est refusée.
Un exemple
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..."
}
}
Lire depuis la copie
| Appel EN 18222 | Requête |
|---|---|
| ReadDPPById (4.2) | GET /api/v1/dpps/{dppId} |
| ReadDPPByProductId (4.3) | GET /api/v1/dppsByProductId/{productId}, un GTIN de 8 à 14 chiffres ou une adresse GS1 Digital Link |
| ReadDPPIdsByProductIds (4.5) | POST /api/v1/dppsByProductIds avec {"productIds": ["09506000134352"]}, 1 000 GTIN au maximum |
| ReadDPPVersionByIdAndDate (4.4) | GET /api/v1/dppsByIdAndDate/{dppId}?date=2026-11-14T12:00:00Z |
Une lecture renvoie la version la plus récente ou, pour une date, la version en vigueur à ce moment-là. Demandez application/json, application/ld+json ou text/html dans l'en-tête Accept (négociation de contenu selon l'EN 18216). Chaque réponse indique qu'il s'agit de la copie de sauvegarde, de quelle version il s'agit et l'empreinte SHA-256 de son contenu.
L'adresse propre du passeport fonctionne aussi : /01/{gtin} suivie des clés GS1 Digital Link.
Les appels de lecture répondent sur un domaine ouvert à la lecture. Un domaine est ouvert lorsqu'une marque fait pointer son domaine de passeports vers la copie. Partout ailleurs, une lecture renvoie 404.
Non proposés : ReadDataElement et UpdateDataElement (EN 18222, article 6).
Reçus
Chaque version stockée reçoit un reçu. Il se compose de deux parties reliées par un point, chacune en base64url sans remplissage :
base64url(receipt as JSON) "." base64url(Ed25519 signature over the first part, as written)
La signature porte sur la première partie exactement telle qu'elle est écrite, il n'y a donc rien à remettre en ordre avant la vérification. Le JSON contient :
| Champ | Signification |
|---|---|
v | La version du format, actuellement 1 |
key_id | La clé qui l'a signé |
receipt_id | L'identifiant de la version stockée |
sender | L'expéditeur de la version |
dpp_id | Le digitalProductPassportId |
version_number | Le numéro de la version, à partir de 1 |
content_sha256 | L'empreinte SHA-256 du contenu, en hexadécimal |
received_at | Le moment où la version a été stockée |
La clé publique
GET /.well-known/backup-receipt-key renvoie :
{
"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 correspond aux 16 premiers chiffres hexadécimaux de l'empreinte SHA-256 de la clé sous sa forme SPKI. Vérifiez un reçu sur la page de vérification ou avec n'importe quelle bibliothèque Ed25519.
Codes d'erreur
Une création ou une mise à jour refusée renvoie l'objet résultat de l'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"
}
]
}
| Statut | Quand (création et mise à jour) |
|---|---|
| 400 | Le corps n'est pas un objet JSON, un attribut obligatoire manque ou est erroné, le passeport est un brouillon, l'identifiant a été modifié, ou l'Idempotency-Key n'est pas valide ou a été utilisée avec une autre requête. |
| 401 | Le jeton d'accès est erroné ou absent. |
| 403 | La connexion n'est plus en vigueur. |
| 404 | Une mise à jour d'un passeport qui n'est pas conservé pour cette connexion. |
| 405 | Une suppression, ou une méthode non autorisée sur ce chemin. |
| 409 | Une création pour un passeport déjà conservé, une mise à jour entrée en conflit avec une autre mise à jour, ou un appel dont l'Idempotency-Key est encore en cours de traitement (avec Retry-After). |
| 413 | Le corps, ou le passeport après la mise à jour, dépasse 1 048 576 octets. |
| 429 | Trop d'appels. Attendez le nombre de secondes indiqué dans Retry-After. |
| 500 | Le passeport n'a pas pu être stocké. Renvoyez-le ; avec la même Idempotency-Key, rien n'est stocké deux fois. |
Les appels de lecture renvoient {"error": "…"} :
| Statut | Quand (lectures) |
|---|---|
| 300 | Plusieurs marques détiennent un passeport à cette adresse. La réponse les énumère. |
| 400 | L'identifiant, le GTIN ou la date manque ou n'est pas valide. |
| 404 | Le passeport n'est pas conservé dans la copie, ou le domaine n'est pas ouvert à la lecture. |
| 405 | Une méthode non autorisée sur ce chemin. |
| 413 | Plus de 1 000 identifiants de produit. |
| 429 | Trop de requêtes. Attendez le nombre de secondes indiqué dans Retry-After. |
| 503 | Temporairement indisponible. Réessayez après Retry-After. |
Conservez une copie de sauvegarde de vos passeports
Créez une organisation avec votre adresse e-mail professionnelle. Une fois qu'elle est approuvée, vous connectez la plateforme qui héberge vos passeports.
Une adresse e-mail professionnelle est requise. Notre équipe examine les nouvelles organisations les jours ouvrés. Le portail est en anglais.