API overview
Quatre ressources, et les relations entre elles
Les passeports décrivent. Les événements consignent. Les attestations prouvent. La résolution sert. Bien séparer ces quatre avant de commencer, c’est ce qui évite de devoir défaire une intégration six mois plus tard.
- Chemin de base
- /v1
- Format
- JSON sur HTTPS
- Auth
- Clés porteuses à portée limitée
Definition
Comment l’API passeport est-elle structurée ?
Autour de quatre ressources. Les passeports portent l’enregistrement produit et sa politique d’accès. Les événements consignent ce qui est arrivé à un objet, sérialisés en GS1 EPCIS 2.0. Les attestations portent des déclarations signées en W3C Verifiable Credentials. La résolution transforme un identifiant GS1 Digital Link en la vue à laquelle un appelant a droit.
Each serialises somebody else’s standard — EPCIS 2.0, VC 2.0 and GS1 Digital Link — so what you build against these endpoints keeps working against a conforming implementation that is not ours.
Le modèle
Quelle ressource répond à quelle question
| Resource | Réponses | Standard |
|---|---|---|
| Passport | "What is this product, and who may see which part?" | Modèle aligné CIRPASS |
| Event | "What happened to this object, where and when?" | GS1 EPCIS 2.0 (JSON-LD) |
| Credential | "Who asserted this, and can I check it myself?" | W3C Verifiable Credentials 2.0 |
| Resolution | "Someone scanned this — what do they get?" | GS1 Digital Link |
Points de terminaison
La surface, en bref
Passeports
Créer, lire, mettre à jour et versionner l’enregistrement produit. Rapport d’écarts par rapport au groupe de produits.
Événements
Ajouter des événements EPCIS 2.0 et interroger l’historique complet d’une identité d’objet.
Attestations
Émettre, présenter, vérifier et révoquer des déclarations signées sur un passeport.
Résolution
Le chemin de lecture public qu’emprunte un scan, renvoyant le niveau adapté à l’appelant.
Authentification
Clés porteuses à portée limitée, par environnement et par capacité.
Référence complète
Chaque point de terminaison, paramètre, forme de réponse et code d’erreur.
Réponses
Questions fréquentes
Quelles sont les ressources principales de l’API ?
Quatre. Les passeports portent l’enregistrement produit et sa politique d’accès. Les événements consignent ce qui est arrivé à un objet, sérialisés en EPCIS 2.0. Les attestations portent des déclarations signées en W3C Verifiable Credentials. La résolution est le chemin de lecture : un identifiant GS1 Digital Link en entrée, la vue adaptée à l’appelant en sortie.
Quand faut-il écrire un événement plutôt que mettre à jour le passeport ?
Mettez le passeport à jour lorsque vous corrigez ou complétez sa description. Écrivez un événement lorsqu’il s’est passé quelque chose — une étape achevée, une garde transférée, une réparation effectuée. La règle empirique : un champ de passeport répond à « qu’est-ce que c’est ? », un événement répond à « que lui est-il arrivé ? ».
Pourquoi la résolution est-elle une préoccupation distincte de la lecture d’un passeport ?
Parce que la résolution est ce que fait un scan, et elle est publique, anonyme et cacheable. Lire un passeport via l’API est authentifié et renvoie ce à quoi votre clé donne droit. Ils servent des appelants différents avec des garanties différentes ; les confondre ferait hériter au chemin public du coût du chemin privé.
L’API est-elle versionnée ?
Oui, dans le chemin — tout est sous `/v1`. Les changements additifs sont livrés sans incrément de version ; tout ce qui casserait une intégration existante obtient une nouvelle version avec période de recouvrement. Les enregistrements de passeport sont versionnés séparément, car un passeport survit à toute version d’API sous laquelle il a été créé.
Next step
Lire ensuite la référence
Vous avez maintenant le modèle. La référence contient le schéma, les paramètres et le contrat d’erreur.