Utiliser l'API REST de DPP Shield
Authentifiez-vous avec une clé API, choisissez les bons scopes, lisez et écrivez produits et passeports, et gérez limites de débit et erreurs.
Équipe éditoriale DPP Shield · Mis à jour:
Créez une clé API dans Settings, API keys, envoyez-la dans l'en-tête X-API-Key (ou comme jeton bearer) à https://api.dppshield.com/api/v1, et générez un client à partir du fichier OpenAPI de la page de référence. Chaque clé appartient à une seule organisation et est limitée par ses scopes.
Où trouver la référence
La référence de l'API, sur /en/developers, liste chaque opération, générée à partir du code de l'API, et propose le fichier OpenAPI 3.1 en téléchargement (https://dppshield.com/openapi.json) à importer dans Postman, Insomnia ou un générateur de code. L'URL de base est https://api.dppshield.com/api/v1. La référence technique est publiée en anglais.
Créer une clé
Envoyez la clé en X-API-Key: dpk_… ou Authorization: Bearer dpk_…. Une clé appartient à son organisation : aucun en-tête d'organisation n'est nécessaire. Elle agit au nom du membre qui l'a créée, pour la traçabilité, et reste limitée par le rôle et le rôle personnalisé de ce membre ; si ce membre part, la clé cesse de fonctionner.
- Ouvrez Settings, API keys (propriétaires et administrateurs).
- Nommez la clé d'après l'intégration qui l'utilisera, choisissez ses scopes et, si vous le souhaitez, une durée de validité en jours.
- Copiez la clé : elle commence par dpk_ et n'est affichée qu'une fois ; DPP Shield ne garde qu'une empreinte et le préfixe visible.
- Conservez-la dans votre gestionnaire de secrets, jamais dans le code source.
Scopes
Une nouvelle clé reçoit dpp:read, dpp:write et compliance:read, sauf choix contraire. Ne donnez à chaque intégration que ce qu'elle utilise, et une clé par intégration, pour qu'en révoquer une ne casse pas les autres.
Scopes disponibles
- dpp:read et dpp:write - les passeports et leurs versions.
- compliance:read - les résultats de validation.
- products:read et products:write - le catalogue.
- product-models:read et product-models:write - modèles et variantes.
- suppliers:write et documents:write - fournisseurs et documents de preuve.
- claims:read, claims:write et evidence-graph:read - allégations et graphe des preuves.
- custody:read et custody:write - le registre de chaîne de traçabilité.
- data-mappings:write - les exécutions du hub d'intégration.
- identity:read, exports:read et analytics:read - vérifications d'identité, exports CSV et statistiques.
Premiers appels
Ces appels couvrent une première intégration habituelle : lire le catalogue, créer un produit et son passeport, enregistrer des données et les valider.
Opérations courantes
- GET /products liste le catalogue ; GET /products/search?q=…&category=…&page=1&pageSize=50 renvoie une page filtrée.
- POST /products crée un produit (name, sku, category, gtin…).
- POST /dpp avec productId et schemaId (eu-<catégorie>, par exemple eu-battery) crée un passeport en brouillon.
- PUT /dpp/{id} avec data enregistre une nouvelle version ; envoyez expectedVersion pour être refusé (409) si quelqu'un a enregistré entre-temps.
- POST /dpp/{id}/validate?markets=EU lance la validation et renvoie les constats.
- GET /dpp/search?status=active renvoie les passeports par statut ; GET /public/dpp/{id} lit un passeport publié sans clé.
Limites de débit
Les requêtes sont comptées par organisation et par heure, avec des budgets distincts pour les lectures et les écritures, fixés par votre forfait. Chaque réponse porte x-ratelimit-limit, x-ratelimit-remaining et x-ratelimit-reset ; au-delà, l'API répond 429 avec Retry-After. Les routes publiques, comme la lecture des passeports et le résolveur GS1, sont comptées par adresse client.
Ce qu'une clé ne peut pas faire
Publier un passeport, décider une dérogation de publication, enregistrer une version dans le registre européen et publier, rappeler ou archiver en masse sont des actes engageants. Sur DPP Shield, ils exigent une personne ayant confirmé un second facteur dans les 15 dernières minutes : une clé API est refusée. Préparez et validez via l'API, et laissez un propriétaire ou un administrateur publier. Une liste d'adresses réseau autorisées de l'organisation s'applique aussi aux clés API.
Erreurs
Les erreurs reviennent en JSON avec un message qui nomme le problème.
Codes de statut
- 400 - le corps ou une valeur n'a pas passé la validation ; le message nomme le champ.
- 401 - la clé est absente, révoquée ou expirée.
- 403 - le scope de la clé, le rôle de son créateur ou un rôle personnalisé n'autorise pas l'opération.
- 404 - l'enregistrement n'existe pas dans cette organisation, ou est hors des espaces de travail d'un membre restreint.
- 409 - le passeport a changé depuis la version envoyée.
- 429 - la limite de débit est atteinte ; attendez la durée de Retry-After.