API reference
Ogni endpoint, raggruppato per risorsa
Passaporti, eventi, credenziali e risoluzione. Il contratto di errore, la paginazione e le regole di idempotenza qui sotto valgono in modo uniforme per tutti e quattro.
- URL base
- api.circuleid.com
- Versione
- /v1
- Auth
- Bearer
Definition
Quali endpoint espone l’API dei passaporti?
Quattro gruppi. Gli endpoint passaporto emettono, leggono, aggiornano e versionano il record di prodotto. Quelli evento aggiungono e interrogano eventi EPCIS 2.0. Quelli credenziale emettono, verificano e revocano dichiarazioni firmate. Quelli di risoluzione servono il percorso pubblico GS1 Digital Link che un supporto scansionato segue.
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.
Endpoint
Passaporti
| Metodo | 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 |
Endpoint
Eventi
| Metodo | 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 |
Endpoint
Credenziali
| Metodo | 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 |
Endpoint
Risoluzione
| Metodo | 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 |
Convenzioni
Errori, paginazione e idempotenza
# 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 resultRisposte
Domande frequenti
Che aspetto ha una risposta di errore?
Uno status HTTP convenzionale con un corpo strutturato che nomina l’errore, il campo fallito e il vincolo violato. Gli errori di validazione sono restituiti per intero anziché uno alla volta, così un record di prodotto malformato mostra ogni problema in una sola risposta invece che in cinque round trip.
Come è gestita la paginazione?
Basata su cursore, non su offset. Le storie degli eventi crescono mentre le leggi, e un offset salterebbe o ripeterebbe silenziosamente record man mano che arrivano nuovi eventi. Il cursore è opaco e stabile: passa quello restituito dalla pagina precedente e fermati quando non ne torna più nessuno.
Le scritture sono idempotenti?
Possono esserlo, e dovrebbero. Inviate una chiave di idempotenza su ogni scrittura che potreste ripetere: una ripetizione con la stessa chiave restituisce il risultato originale invece di creare un secondo passaporto o un evento duplicato. Senza, un timeout di rete su una scrittura vi lascia nell’impossibilità di sapere se è andata a buon fine.
Qual è la differenza tra leggere un passaporto e risolverlo?
La lettura è autenticata e restituisce ciò a cui la tua chiave API dà diritto. La risoluzione è ciò che fa una scansione: pubblica, anonima, cacheabile, e restituisce il livello che le credenziali del chiamante consentono — per la maggior parte, il livello pubblico. Sono percorsi distinti, con proprietà di prestazione e riservatezza diverse.
Next step
Emetterne uno con una chiave sandbox
Il modo più rapido per giudicare un’API è inviarle un record di prodotto reale e leggere che cosa torna indietro.