API du passeport numérique de produit : documentation pour développeurs

Aperçu

L’API client est une interface REST qui utilise JSON. Elle travaille sur les données de votre mandant, c’est-à-dire les mêmes produits et passeports que ceux de l’application web. Les usages typiques sont le raccordement d’un système ERP ou PLM, une synchronisation nocturne des données de base ou un script qui récupère des codes QR à imprimer.

L’URL de base est https://dpp.com2u.selfhost.eu/api/v1/integration. Toutes les réponses sont en JSON, sauf les téléchargements de codes QR et de PDF.

Télécharger la spécification

La référence lisible par machine de tous les endpoints, champs, exemples et réponses d’erreur est une spécification OpenAPI 3.1 avec le schéma de sécurité ApiKeyAuth :

• Télécharger openapi.json
• Télécharger openapi.yaml

L’API elle-même fournit le même fichier à GET /api/v1/integration/openapi.json, sans clé. Importez-le dans Swagger UI, Postman ou le générateur de code de votre choix. Les descriptions à l’intérieur du fichier sont rédigées en allemand.

Démarrage rapide

1. Inscrivez-vous ou connectez-vous. L’API fait partie des offres payantes, voir Tarifs.
2. Ouvrez l’espace Mandant dans la plateforme et générez la clé d’API. Copiez-la immédiatement, car elle n’est affichée qu’une seule fois.
3. Testez la connexion :

curl -H "X-API-Key: $DPP_API_KEY" \
  https://dpp.com2u.selfhost.eu/api/v1/integration/me

La réponse indique votre mandant, les scopes de la clé, votre offre et votre consommation d’appels d’API.

Authentification

Envoyez la clé à chaque appel dans l’en-tête X-API-Key. Authorization: Bearer dpp_key_… fonctionne de la même manière. Le mandant est toujours déduit de la clé ; un ID de mandant transmis comme paramètre est ignoré. L’API n’accepte pas les jetons de session de l’application web.

La clé appartient à la personne qui l’a générée. Les actions s’exécutent avec les droits de cette personne en tant que propriétaire ou administrateur. Si la personne perd ce rôle, l’API répond par 403 jusqu’à la génération d’une nouvelle clé. Générer une nouvelle clé révoque immédiatement la précédente. La plateforme ne stocke qu’un hachage SHA-256 de la clé.

Endpoints

Tous les chemins se trouvent sous /api/v1/integration. Chaque endpoint exige un scope ; une nouvelle clé porte les quatre.

Créer un produit

name est obligatoire. Sans schema_key, le schéma par défaut de votre mandant s’applique ; GET /schemas renvoie les clés disponibles. Vous pouvez transmettre directement les champs de données. field_status définit le statut des valeurs, et seules les valeurs approved alimentent un passeport.

curl -X POST https://dpp.com2u.selfhost.eu/api/v1/integration/products \
  -H "X-API-Key: $DPP_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Battery module X1","category":"Industrial batteries",
       "manufacturer_ref":"ART-4711","schema_key":"battery-v1",
       "fields":{"battery_chemistry":"LFP"},"field_status":"approved"}'

La réponse avec le statut 201 contient l’id du produit. C’est aussi l’identifiant unique de produit encodé dans le code QR. Le quota de produits de votre offre s’applique comme dans l’application web.

Publier un passeport, télécharger le code QR et le PDF

Un passeport fige les champs de données validés sous forme de nouvelle version. Si des champs obligatoires manquent, l’API répond par 422 et les énumère dans missing_fields.

curl -X POST -H "X-API-Key: $DPP_API_KEY" \
  https://dpp.com2u.selfhost.eu/api/v1/integration/products/{id}/passports

curl -o qr.png -H "X-API-Key: $DPP_API_KEY" \
  "https://dpp.com2u.selfhost.eu/api/v1/integration/products/{id}/passport/qr?format=png&size=600"

curl -o passport.pdf -H "X-API-Key: $DPP_API_KEY" \
  https://dpp.com2u.selfhost.eu/api/v1/integration/products/{id}/passport/pdf

Pour un code QR vectoriel, utilisez format=svg. Le PDF n’existe qu’après la publication ; avant, l’API répond par 404. Le code QR renvoie vers la page publique du passeport, voir Créer un passeport numérique de produit depuis Excel pour en savoir plus.

Codes d’erreur

Pour 401 et 403, detail contient un objet avec code et message, par exemple insufficient_scope ou api_not_in_plan. Pour 402, detail indique la ressource, la limite et la consommation à ce jour.

Limites

Via l’API, vous renseignez des champs de données au niveau du produit. Les champs de lots ou d’unités individuelles se gèrent dans l’application web. Il n’y a pas de limite de débit, mais un quota d’appels par offre ; chaque appel authentifié compte. La récupération de la spécification ne compte pas. Les offres et quotas actuels figurent sur la page Tarifs. Pour un import en masse sans l’API, utilisez le modèle de données.