CirculeID

Documentation

Commencer ici

Tout ce qu’il faut pour émettre un passeport, ajouter des événements de chaîne et vérifier une attestation — avec les standards sur lesquels chacun se mappe, si bien que rien de ce que vous construisez n’est captif de cette plateforme.

Référence de l’APIObtenir une clé d’API
Protocole
JSON sur HTTPS
Événements
EPCIS 2.0 JSON-LD
Attestations
W3C VC 2.0

Definition

Comment émettre un passeport numérique de produit via une API ?

Créez une ressource passeport sur un identifiant GS1 avec l’enregistrement produit, ajoutez des événements EPCIS 2.0 au fil des mouvements, et émettez des W3C Verifiable Credentials pour les déclarations à prouver. La lecture résout l’identifiant et renvoie la vue à laquelle les attestations de l’appelant donnent droit.

The wire formats are not ours: GS1 Digital Link for identity, EPCIS 2.0 for events, and W3C Verifiable Credentials for claims.

Démarrage rapide

Votre premier passeport

Une requête authentifiée. La réponse porte le Digital Link résolvable et la charge utile de support que vous imprimez ou encodez.
POST /v1/passports
curl https://api.circuleid.com/v1/passports \
  -H "Authorization: Bearer $CIRCULEID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gtin": "09506000134352",
    "productGroup": "textiles",
    "level": "model",
    "record": {
      "name": "Merino Crew Knit",
      "materials": [
        { "name": "merino wool", "share": 0.82, "certification": "RWS" },
        { "name": "recycled polyamide", "share": 0.18 }
      ]
    }
  }'

Illustrative request shape. The API reference carries the authoritative schema and error contract.

Référence

Où aller ensuite

Huit pages couvrent toute la surface. Elles sont ordonnées comme une intégration se déroule habituellement.

Parcours d’intégration

De la clé d’API à un passeport résolvable

Quatre étapes. La deuxième est la seule qui prenne généralement plus d’un après-midi.
  1. 01

    Obtenir une clé à portée limitée

    Les clés sont limitées par environnement et par capacité, si bien qu’un service d’émission ne détient jamais d’accès en lecture aux données restreintes.

  2. 02

    Cartographier l’enregistrement produit

    Publiez votre référentiel produit sur son identifiant GS1. La réponse nomme les champs que le groupe de produits exige encore.

  3. 03

    Ajouter événements et attestations

    Écrivez des événements EPCIS 2.0 à mesure que l’article circule ; émettez des certificats pour les allégations qui doivent résister à un examen indépendant.

  4. 04

    Résoudre et s’abonner

    L’identifiant se résout vers la vue adaptée à l’appelant, et les webhooks préviennent vos systèmes dès que quelque chose change.

Réponses

Questions fréquentes

De quoi ai-je besoin avant de pouvoir émettre un passeport ?

Une clé d’API, un identifiant GS1 pour le produit, et l’enregistrement produit lui-même. Si vous n’avez pas encore d’identifiants GS1, c’est la première dépendance à lever — ils viennent de votre organisation membre GS1, pas de nous, car l’identité doit être globalement unique en dehors de notre plateforme.

Y a-t-il un bac à sable ?

Oui. Les clés sont limitées à un environnement : les clés bac à sable ne peuvent pas toucher aux passeports de production, et les clés de production ne peuvent pas être utilisées par accident dans un banc de test. Les passeports du bac à sable se résolvent exactement comme ceux de production, sur un nom d’hôte de résolveur distinct.

Quels sont les formats de transport ?

JSON sur HTTPS pour l’API. Les événements suivent la sérialisation JSON-LD de GS1 EPCIS 2.0, et les attestations le modèle de données W3C Verifiable Credentials 2.0. Là où un standard définit une représentation, nous l’utilisons plutôt que d’en inventer une : l’outillage existant pour ces standards fonctionne donc sur notre production.

Comment traiter les erreurs ?

L’API renvoie des codes de statut HTTP classiques avec un corps d’erreur structuré nommant le champ et la contrainte en échec. Les erreurs de validation sont renvoyées en bloc plutôt qu’une à une, si bien qu’un enregistrement produit malformé révèle tous ses problèmes en une réponse au lieu de cinq allers-retours.

Comment obtenons-nous du support pendant l’intégration ?

Par le canal de support rattaché à votre compte, ou par le formulaire de contact si vous êtes encore en évaluation. Les questions d’intégration qui révèlent une lacune dans la documentation sont traitées comme des défauts de documentation : c’est le seul moyen pour qu’une référence reste exacte à mesure que l’API grandit.

Next step

Émettre un passeport sur votre propre GTIN

Obtenez une clé bac à sable, envoyez un enregistrement produit, et voyez ce que résout le support renvoyé.

Obtenir une clé d’APIRéférence de l’API

Index

À lire également