CirculeID

API reference

Cada endpoint, agrupado por recurso

Passaportes, eventos, credenciais e resolução. O contrato de erros, a paginação e as regras de idempotência abaixo aplicam-se de forma uniforme aos quatro.

Obter uma chave de APIComece por perceber o modelo
URL base
api.circuleid.com
Versão
/v1
Auth
Bearer

Definition

Que pontos de extremidade expõe a API de passaportes?

Quatro grupos. Os endpoints de passaporte emitem, leem, atualizam e versionam o registo de produto. Os de eventos acrescentam e consultam eventos EPCIS 2.0. Os de credenciais emitem, verificam e revogam declarações assinadas. Os de resolução servem o caminho público GS1 Digital Link que um suporte digitalizado 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.

Endpoints

Passaportes

O registo do produto e a sua política de acesso. O ponto de extremidade de lacunas é aquele que a maioria das integrações acaba por chamar com mais frequência.
Passports endpoints
MétodoPathPurpose
POST/v1/passportsIssue 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}/gapsFields the product group’s delegated act still requires
GET/v1/passports/{id}/versionsThe record’s version history
GET/v1/passportsList and filter passports in your tenant

Endpoints

Eventos

Histórico EPCIS 2.0 apenas por acrescento. Use o modo em massa para carregar histórico; o endpoint unitário está otimizado para latência, não para débito.
Events endpoints
MétodoPathPurpose
POST/v1/eventsAppend one EPCIS 2.0 event
POST/v1/events/bulkAsynchronous bulk ingestion; returns a job
GET/v1/eventsQuery by object identity, business step or time
GET/v1/jobs/{id}Status of a bulk ingestion job

Endpoints

Credenciais

Declarações assinadas. A verificação está ao alcance de quem detiver a credencial e não requer estes endpoints — existem por comodidade, não como dependência.
Credentials endpoints
MétodoPathPurpose
POST/v1/credentialsIssue a signed claim against a passport
GET/v1/credentials/{id}Retrieve a credential and its status
POST/v1/credentials/{id}/revokeRevoke; verification fails from this point
POST/v1/credentials/verifyVerify a credential you were presented

Endpoints

Resolução

O caminho público. Sem autenticação, passível de cache, e devolvendo o nível a que as credenciais de quem chama dão direito.
Resolution endpoints
MétodoPathPurpose
GET/01/{gtin}GS1 Digital Link resolution — the path a scan takes
GET/01/{gtin}/21/{serial}Resolution for an item-level passport

Convenções

Erros, paginação e idempotência

Aplicam-se a todos os pontos de extremidade acima. Tratá-los uma só vez no seu cliente é melhor do que tratá-los em cada local de chamada.
Convenções
# 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 result

Respostas

Perguntas frequentes

Qual é o aspeto de uma resposta de erro?

Um estado HTTP convencional com um corpo estruturado que identifica o erro, o campo que falhou e a restrição violada. Os erros de validação são devolvidos por inteiro em vez de um de cada vez, pelo que um registo malformado revela todos os problemas numa resposta em vez de em cinco idas e voltas.

Como é tratada a paginação?

Baseado em cursor e não em deslocamento. Os históricos de eventos crescem enquanto os lê, e um deslocamento saltaria ou repetiria registos em silêncio à medida que chegam novos eventos. O cursor é opaco e estável; passe o que a página anterior devolveu e pare quando nenhum voltar.

As escritas são idempotentes?

Podem ser, e devem ser. Envie uma chave de idempotência em qualquer escrita que possa vir a repetir: uma repetição com a mesma chave devolve o resultado original em vez de criar um segundo passaporte ou um evento duplicado. Sem ela, um tempo de espera de rede numa escrita deixa-o sem saber se ela foi aplicada.

Qual é a diferença entre ler um passaporte e resolvê-lo?

A leitura é autenticada e devolve aquilo a que a sua chave de API dá direito. A resolução é o que uma leitura faz: pública, anónima, cacheável, devolvendo o nível que as credenciais de quem chama permitem — para a maioria, o nível público. São caminhos distintos, com propriedades de desempenho e privacidade diferentes.

Next step

Emitir um com uma chave de sandbox

A forma mais rápida de avaliar uma API é enviar-lhe um registo de produto real e ler o que volta.

Pedir acessoVer exemplos funcionais

Index

Leituras relacionadas