Examples
Os cinco pedidos que uma integração realmente faz
Emitir um passaporte. Acrescentar um evento. Assinar uma declaração de fornecedor. Verificar uma. Servir uma leitura. A maioria das integrações são estas cinco, repetidas — todo o resto é mapeamento.
- Comece com
- Emitir + acrescentar
- Acrescentar mais tarde
- Declarações assinadas
- Ambiente
- Primeiro a sandbox
Definition
O que faz realmente uma integração de passaportes típica?
Cinco operações, repetidas. Emitir um passaporte sobre um identificador GS1. Acrescentar eventos EPCIS 2.0 à medida que o produto se move. Recolher declarações assinadas dos fornecedores. Verificar uma declaração que lhe é apresentada. E servir a vista pública quando alguém digitaliza o suporte aposto no produto.
The volume is dominated by the first two. The difficulty is dominated by the third, which is a supplier relationship problem rather than a technical one.
01
Emitir um passaporte
curl https://api.circuleid.com/v1/passports \
-H "Authorization: Bearer $CIRCULEID_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"gtin": "09506000134352",
"productGroup": "textiles",
"level": "model",
"record": {
"name": "Merino Crew Knit",
"materials": [
{ "name": "merino wool", "share": 0.82, "certification": "RWS" },
{ "name": "recycled polyamide", "share": 0.18 }
],
"carbonFootprint": { "value": 14.2, "unit": "kgCO2e", "method": "ISO 14067" }
}
}'02
Acrescentar um evento da cadeia
curl https://api.circuleid.com/v1/events \
-H "Authorization: Bearer $CIRCULEID_API_KEY" \
-d '{
"type": "ObjectEvent",
"action": "OBSERVE",
"eventTime": "2026-03-14T09:22:00+01:00",
"epcList": ["urn:epc:id:sgtin:0950600.013435.SN8817403"],
"bizStep": "urn:epcglobal:cbv:bizstep:commissioning",
"disposition": "urn:epcglobal:cbv:disp:active",
"bizLocation": { "id": "urn:epc:id:sgln:0950600.00001.0" }
}'03
Assinar uma declaração de fornecedor
curl https://api.circuleid.com/v1/credentials \
-H "Authorization: Bearer $SUPPLIER_API_KEY" \
-d '{
"type": "RecycledContentCredential",
"issuer": "did:web:mill.example.com",
"subject": "01/09506000134352",
"validUntil": "2027-03-14T00:00:00Z",
"claim": {
"material": "polyamide",
"recycledShare": 0.18,
"basis": "mass",
"chainOfCustody": "mass-balance"
}
}'04
Verificar uma alegação que lhe foi apresentada
curl https://api.circuleid.com/v1/credentials/verify \
-H "Authorization: Bearer $CIRCULEID_API_KEY" \
-d '{ "credential": { /* the credential as presented */ } }'
# {
# "verified": true,
# "issuer": "did:web:mill.example.com",
# "issuedAt": "2026-03-14T09:31:02Z",
# "status": "active" # "revoked" fails verification
# }05
Servir uma leitura
# What the phone requests when a consumer scans the carrier:
curl https://id.circuleid.com/01/09506000134352 \
-H "Accept: application/json"
# A browser gets the rendered public passport instead.
# A verified recycler presenting a credential gets the treatment tier
# from the same URL — the resolver decides, not the caller.Padrões
Onde costuma residir cada um
Pipeline de emissão
Uma tarefa agendada que lê o PLM e emite passaportes para a série de produção seguinte.
Ingestão de eventos
Um serviço que traduz mensagens WMS e MES em eventos EPCIS à medida que ocorrem.
Portal de fornecedores
Onde os fornecedores de segundo nível submetem e assinam as alegações que o próprio não pode fazer.
Loja
Ler o nível público para mostrar dados de sustentabilidade fundamentados num anúncio.
O próprio suporte
Nenhum código da sua parte — o resolvedor serve a leitura diretamente.
Receção da recolha
Ler o nível de tratamento na linha de uma instalação de devoluções ou de reciclagem.
Respostas
Perguntas frequentes
De que exemplo devo partir?
Emitir um passaporte e depois acrescentar um evento. Essas duas operações cobrem a maior parte do tráfego de uma integração e obrigam-no a fixar o modelo de identidade — modelo, lote ou artigo — que é a decisão de que tudo o resto depende e a mais difícil de mudar depois.
Tenho de lidar com credenciais logo no primeiro dia?
Não. Um passaporte com dados não assinados continua a ser um passaporte funcional; apenas não consegue demonstrar quem afirmou cada valor. A maioria dos programas emite primeiro e acrescenta declarações assinadas de fornecedores à medida que estes se integram, que é também a ordem que a realidade permite.
O que recebe realmente o consumidor de uma leitura?
O nível público do passaporte, resolvido a partir do identificador GS1 Digital Link contido no suporte, apresentado como página para um navegador ou devolvido em JSON a um sistema que o peça. Sem autenticação, sem conta e sem perfil da pessoa que faz a leitura.
Podemos testar sem tocar na produção?
Sim. As chaves de sandbox resolvem contra um nome de anfitrião separado, e os passaportes de sandbox comportam-se exatamente como os de produção. Como um passaporte de produção é um artefacto público de longa duração, a separação é imposta e não convencional — uma chave de sandbox simplesmente não chega à produção.
Next step
Corra as duas primeiras com uma chave de sandbox
Emita um passaporte e acrescente um evento. Isso basta para fixar o modelo de identidade, a decisão em que tudo o resto assenta.