API reference
Chaque point de terminaison, groupé par ressource
Passeports, événements, attestations et résolution. Le contrat d’erreur, la pagination et les règles d’idempotence ci-dessous s’appliquent uniformément aux quatre.
- URL de base
- api.circuleid.com
- Version
- /v1
- Auth
- Bearer
Definition
Quels points de terminaison l’API passeport expose-t-elle ?
Quatre groupes. Les points de terminaison passeport émettent, lisent, mettent à jour et versionnent l’enregistrement produit. Les points événement ajoutent et interrogent des événements EPCIS 2.0. Les points attestation émettent, vérifient et révoquent des déclarations signées. Les points résolution servent le chemin public GS1 Digital Link que suit un support scanné.
If you have not read the API model yet, start there. The relationships between these four decide which one you should be calling, and that is the choice most integrations get wrong first.
Points de terminaison
Passeports
| Méthode | Path | Purpose |
|---|---|---|
| POST | /v1/passports | Issue a passport against a GS1 identifier |
| GET | /v1/passports/{id} | Read the full record your key is entitled to |
| PATCH | /v1/passports/{id} | Update the record; material changes are versioned |
| GET | /v1/passports/{id}/gaps | Fields the product group’s delegated act still requires |
| GET | /v1/passports/{id}/versions | The record’s version history |
| GET | /v1/passports | List and filter passports in your tenant |
Points de terminaison
Événements
| Méthode | Path | Purpose |
|---|---|---|
| POST | /v1/events | Append one EPCIS 2.0 event |
| POST | /v1/events/bulk | Asynchronous bulk ingestion; returns a job |
| GET | /v1/events | Query by object identity, business step or time |
| GET | /v1/jobs/{id} | Status of a bulk ingestion job |
Points de terminaison
Attestations
| Méthode | Path | Purpose |
|---|---|---|
| POST | /v1/credentials | Issue a signed claim against a passport |
| GET | /v1/credentials/{id} | Retrieve a credential and its status |
| POST | /v1/credentials/{id}/revoke | Revoke; verification fails from this point |
| POST | /v1/credentials/verify | Verify a credential you were presented |
Points de terminaison
Résolution
| Méthode | Path | Purpose |
|---|---|---|
| GET | /01/{gtin} | GS1 Digital Link resolution — the path a scan takes |
| GET | /01/{gtin}/21/{serial} | Resolution for an item-level passport |
Conventions
Erreurs, pagination et idempotence
# Validation errors return every problem at once.
HTTP/1.1 422 Unprocessable Entity
{
"error": "validation_failed",
"problems": [
{ "field": "materials[0].share", "constraint": "must sum to 1.0" },
{ "field": "carbonFootprint.method", "constraint": "required for this group" }
]
}
# Pagination is cursor-based: an offset would skip or repeat
# records as new events arrive while you are reading.
GET /v1/events?object=01/09506000134352&cursor=ev_8f21...
# Send an idempotency key on any write you might retry.
POST /v1/passports
Idempotency-Key: 6f1c9a7e-... # a repeat returns the original resultRéponses
Questions fréquentes
À quoi ressemble une réponse d’erreur ?
Un statut HTTP classique avec un corps structuré nommant l’erreur, le champ en échec et la contrainte violée. Les erreurs de validation sont renvoyées en bloc plutôt qu’une à une, si bien qu’un enregistrement mal formé révèle tous ses problèmes en une réponse au lieu de cinq allers-retours.
Comment la pagination est-elle gérée ?
Par curseur et non par décalage. Les historiques d’événements grossissent pendant que vous les lisez, et un décalage sauterait ou répéterait silencieusement des enregistrements à mesure que de nouveaux événements arrivent. Le curseur est opaque et stable ; passez celui renvoyé par la page précédente et arrêtez-vous quand il n’en revient plus.
Les écritures sont-elles idempotentes ?
Elles peuvent l’être, et devraient l’être. Envoyez une clé d’idempotence sur toute écriture susceptible d’être rejouée : une répétition avec la même clé renvoie le résultat initial au lieu de créer un second passeport ou un événement en double. Sans elle, un délai réseau dépassé sur une écriture vous laisse dans l’incapacité de savoir si elle a été appliquée.
Quelle est la différence entre lire un passeport et le résoudre ?
La lecture est authentifiée et renvoie ce à quoi votre clé d’API donne droit. La résolution est ce que fait un scan : publique, anonyme, cacheable, et renvoyant le niveau que les attestations de l’appelant permettent — pour la plupart, le niveau public. Ce sont deux chemins distincts, aux propriétés de performance et de confidentialité différentes.
Next step
En émettre un avec une clé bac à sable
La façon la plus rapide de juger une API est de lui envoyer un vrai enregistrement produit et de lire ce qui revient.