API reference
Elk endpoint, gegroepeerd per resource
Paspoorten, gebeurtenissen, credentials en resolutie. Het foutcontract, de paginering en de idempotentieregels hieronder gelden uniform voor alle vier.
- Basis-URL
- api.circuleid.com
- Versie
- /v1
- Auth
- Bearer
Definition
Welke endpoints biedt de paspoort-API?
Vier groepen. Paspoort-endpoints geven het productrecord uit, lezen, werken bij en versioneren het. Gebeurtenis-endpoints voegen EPCIS 2.0-ketengebeurtenissen toe en bevragen ze. Credential-endpoints geven ondertekende claims uit, verifiëren en trekken ze in. Resolutie-endpoints bedienen het publieke GS1 Digital Link-pad dat een gescande drager volgt.
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.
Endpoints
Paspoorten
| Methode | 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 |
Endpoints
Gebeurtenissen
| Methode | 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 |
Endpoints
Credentials
| Methode | 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 |
Endpoints
Resolutie
| Methode | 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 |
Conventies
Fouten, paginering en idempotentie
# 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 resultAntwoorden
Veelgestelde vragen
Hoe ziet een foutantwoord eruit?
Een gewone HTTP-status met een gestructureerde body die de fout benoemt, het veld dat faalde en de geschonden voorwaarde. Validatiefouten komen volledig terug in plaats van één voor één, zodat een onjuist productrecord elk probleem in één response toont in plaats van over vijf rondgangen.
Hoe wordt paginering afgehandeld?
Op cursor, niet op offset. Gebeurtenishistories groeien terwijl u ze leest, en een offset zou records stilzwijgend overslaan of herhalen naarmate nieuwe gebeurtenissen binnenkomen. De cursor is ondoorzichtig en stabiel; geef de cursor door die de vorige pagina teruggaf en stop wanneer er geen meer terugkomt.
Zijn schrijfacties idempotent?
Dat kan, en dat hoort ook. Stuur een idempotency key mee bij elke schrijfactie die u mogelijk opnieuw uitvoert; een herhaling met dezelfde sleutel geeft het oorspronkelijke resultaat terug in plaats van een tweede paspoort of een dubbele gebeurtenis aan te maken. Zonder die sleutel laat een netwerktime-out bij een schrijfactie u in het ongewisse of zij is doorgevoerd.
Wat is het verschil tussen een paspoort lezen en een paspoort resolven?
Lezen is geauthenticeerd en geeft terug waar uw API-sleutel recht op heeft. Resolven is wat een scan doet: publiek, anoniem, cachebaar, en het geeft de laag terug die de credentials van de aanroeper toestaan — voor de meesten de publieke laag. Het zijn aparte paden met andere prestatie- en privacykenmerken.
Next step
Er een uitgeven met een sandboxsleutel
De snelste manier om een API te beoordelen is haar een echt productrecord te sturen en te lezen wat terugkomt.