API reference
Cada endpoint, agrupado por recurso
Pasaportes, eventos, credenciales y resolución. El contrato de errores, la paginación y las reglas de idempotencia de abajo se aplican por igual a los cuatro.
- URL base
- api.circuleid.com
- Versión
- /v1
- Auth
- Bearer
Definition
¿Qué endpoints expone la API de pasaportes?
Cuatro grupos. Los endpoints de pasaporte emiten, leen, actualizan y versionan el registro de producto. Los de eventos añaden y consultan eventos EPCIS 2.0. Los de credenciales emiten, verifican y revocan declaraciones firmadas. Los de resolución sirven la ruta pública GS1 Digital Link que sigue un portador escaneado.
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
Pasaportes
| Método | 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
Eventos
| Método | 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
Credenciales
| Método | 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
Resolución
| Método | 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 |
Convenciones
Errores, paginación e idempotencia
# 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 resultRespuestas
Preguntas frecuentes
¿Qué aspecto tiene una respuesta de error?
Un estado HTTP convencional con un cuerpo estructurado que nombra el error, el campo que falló y la restricción incumplida. Los errores de validación se devuelven completos y no de uno en uno, de modo que un registro mal formado muestra todos sus problemas en una respuesta en vez de en cinco viajes de ida y vuelta.
¿Cómo se gestiona la paginación?
Basado en cursor, no en desplazamiento. Los historiales de eventos crecen mientras los lee, y un desplazamiento saltaría o repetiría registros en silencio a medida que llegan nuevos eventos. El cursor es opaco y estable; pase el que devolvió la página anterior y deténgase cuando no vuelva ninguno.
¿Son idempotentes las escrituras?
Pueden serlo, y deberían serlo. Envíe una clave de idempotencia en cualquier escritura que pudiera reintentar: una repetición con la misma clave devuelve el resultado original en lugar de crear un segundo pasaporte o un evento duplicado. Sin ella, un tiempo de espera de red en una escritura le deja sin saber si se aplicó.
¿Cuál es la diferencia entre leer un pasaporte y resolverlo?
La lectura está autenticada y devuelve aquello a lo que su clave de API da derecho. La resolución es lo que hace un escaneo: pública, anónima, cacheable, y devuelve el nivel que permiten las credenciales del llamante, que para la mayoría es el público. Son vías distintas con propiedades de rendimiento y privacidad distintas.
Next step
Emitir uno con una clave de sandbox
La forma más rápida de juzgar una API es enviarle un registro de producto real y leer lo que devuelve.