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 18222RequêteRéponse
CreateDPP (4.6)POST /api/v1/dpps avec le passeport complet201 et la version stockée
UpdateDPPById (4.7)PATCH /api/v1/dpps/{dppId} avec les parties modifiées200 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, batch ou item.
  • dppSchemaVersion
  • dppStatus : active, inactive, archived ou invalid. Seuls les passeports publiés sont sauvegardés, un brouillon est donc refusé.
  • lastUpdated : ISO 8601 avec un fuseau horaire, par exemple 2026-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) et contentSpecificationIds (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 18222Requê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 :

ChampSignification
vLa version du format, actuellement 1
key_idLa clé qui l'a signé
receipt_idL'identifiant de la version stockée
senderL'expéditeur de la version
dpp_idLe digitalProductPassportId
version_numberLe numéro de la version, à partir de 1
content_sha256L'empreinte SHA-256 du contenu, en hexadécimal
received_atLe 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"
    }
  ]
}
StatutQuand (création et mise à jour)
400Le 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.
401Le jeton d'accès est erroné ou absent.
403La connexion n'est plus en vigueur.
404Une mise à jour d'un passeport qui n'est pas conservé pour cette connexion.
405Une suppression, ou une méthode non autorisée sur ce chemin.
409Une 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).
413Le corps, ou le passeport après la mise à jour, dépasse 1 048 576 octets.
429Trop d'appels. Attendez le nombre de secondes indiqué dans Retry-After.
500Le 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": "…"} :

StatutQuand (lectures)
300Plusieurs marques détiennent un passeport à cette adresse. La réponse les énumère.
400L'identifiant, le GTIN ou la date manque ou n'est pas valide.
404Le passeport n'est pas conservé dans la copie, ou le domaine n'est pas ouvert à la lecture.
405Une méthode non autorisée sur ce chemin.
413Plus de 1 000 identifiants de produit.
429Trop de requêtes. Attendez le nombre de secondes indiqué dans Retry-After.
503Temporairement 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.