API overview
Quatro recursos, e as relações entre eles
Os passaportes descrevem. Os eventos registam. As credenciais provam. A resolução serve. Ter estes quatro bem separados antes de começar é o que evita ter de desfazer uma integração seis meses depois.
- Caminho base
- /v1
- Formato
- JSON sobre HTTPS
- Auth
- Chaves bearer com âmbito
Definition
Como está estruturada a API do passaporte?
Em torno de quatro recursos. Os passaportes contêm o registo de produto e a respetiva política de acesso. Os eventos registam o que aconteceu a um objeto, serializados como GS1 EPCIS 2.0. As credenciais transportam declarações assinadas como W3C Verifiable Credentials. A resolução transforma um identificador GS1 Digital Link na vista a que quem chama tem direito.
Each serialises somebody else’s standard — EPCIS 2.0, VC 2.0 and GS1 Digital Link — so what you build against these endpoints keeps working against a conforming implementation that is not ours.
O modelo
Que recurso responde a que pergunta
| Resource | Respostas | Norma |
|---|---|---|
| Passport | "What is this product, and who may see which part?" | Modelo alinhado com CIRPASS |
| Event | "What happened to this object, where and when?" | GS1 EPCIS 2.0 (JSON-LD) |
| Credential | "Who asserted this, and can I check it myself?" | W3C Verifiable Credentials 2.0 |
| Resolution | "Someone scanned this — what do they get?" | GS1 Digital Link |
Endpoints
A superfície, em resumo
Passaportes
Criar, ler, atualizar e versionar o registo do produto. Relatório de lacunas face ao grupo de produtos.
Eventos
Acrescente eventos EPCIS 2.0 e consulte o histórico completo de uma identidade de objeto.
Credenciais
Emitir, apresentar, verificar e revogar declarações assinadas num passaporte.
Resolução
O caminho de leitura público que uma leitura por scan percorre, devolvendo o nível adequado a quem chama.
Autenticação
Chaves bearer com âmbito, por ambiente e por capacidade.
Referência completa
Cada endpoint, parâmetro, forma de resposta e código de erro.
Respostas
Perguntas frequentes
Quais são os recursos centrais da API?
Quatro. Os passaportes contêm o registo de produto e a sua política de acesso. Os eventos registam o que aconteceu a um objeto, serializados como EPCIS 2.0. As credenciais transportam declarações assinadas como W3C Verifiable Credentials. A resolução é o caminho de leitura: entra um identificador GS1 Digital Link, sai a vista adequada a quem chama.
Quando devo escrever um evento em vez de atualizar o passaporte?
Atualize o passaporte quando estiver a corrigir ou a completar a sua descrição. Escreva um evento quando algo aconteceu — uma etapa concluída, uma custódia transferida, uma reparação efetuada. A regra prática é que um campo do passaporte responde a «o que é isto?» e um evento responde a «o que lhe aconteceu?».
Porque é a resolução uma questão distinta da leitura de um passaporte?
Porque a resolução é o que uma leitura faz, e é pública, anónima e cacheável. Ler um passaporte pela API é autenticado e devolve aquilo a que a sua chave dá direito. Servem interlocutores diferentes com garantias diferentes, pelo que confundi-los faria o caminho público herdar o custo do privado.
A API tem versionamento?
Sim, no caminho — está tudo sob `/v1`. As alterações aditivas são publicadas sem mudança de versão; tudo o que quebrasse uma integração existente recebe uma nova versão com período de sobreposição. Os registos de passaporte são versionados em separado, porque um passaporte sobrevive a qualquer versão da API com que foi criado.
Next step
Ler a seguir a referência
Já tem o modelo. A referência traz o esquema, os parâmetros e o contrato de erros.