SDKs
Clientes leves e uma saída de emergência que funciona mesmo
Tipos gerados a partir do mesmo esquema contra o qual a API valida, repetições que respeitam os cabeçalhos de taxa, e verificação de assinatura que de outro modo implementaria subtilmente mal. Todo o resto está à distância de um pedido em bruto.
- Tipado a partir de
- O esquema da API
- Versão principal
- Acompanha /v1
- Pedidos em bruto
- Sempre disponível
Definition
O que lhe dá uma biblioteca cliente da API de passaportes?
Tipos gerados a partir do esquema contra o qual a API valida, para que um campo errado falhe em tempo de compilação e não como erro em execução. Repetição e backoff que respeitam os cabeçalhos de limite de taxa. Verificação da assinatura de webhooks sobre o corpo em bruto. E uma saída de emergência para os pedidos que o cliente não modela.
None of it is essential. Every payload is JSON following a published standard, so an integration written with an HTTP client and no SDK at all is a completely reasonable choice — and one some security policies require.
Clientes
O que está disponível
| Language | Typical use | Notes |
|---|---|---|
| TypeScript / Node.js | Storefronts, webhook receivers, serverless issuing | Types generated from the schema; works in edge runtimes |
| Python | Data pipelines, PLM and ERP integration jobs | Fits where the sustainability data work already happens |
| Go | High-throughput event ingestion services | For services writing events continuously rather than in batches |
| Anything else | Direct HTTP | JSON, GS1 and W3C standards — no client required |
Forma
Como é usar um
import { CirculeID } from '@circuleid/sdk';
const circuleid = new CirculeID({ apiKey: process.env.CIRCULEID_API_KEY });
const passport = await circuleid.passports.create({
gtin: '09506000134352',
productGroup: 'textiles',
level: 'model',
record: { name: 'Merino Crew Knit' },
});
// The gap report is part of the response, not a separate call:
// which fields the delegated act still requires for this group.
console.log(passport.gaps);
// Escape hatch — same auth, same retries, no abstraction in the way.
await circuleid.request('POST', '/v1/events', { body: epcisEvent });Aquilo de que se ocupam
As partes que vale a pena não escrever por si próprio
Tipos gerados
A partir do mesmo esquema com que a API valida, pelo que os dois não podem divergir.
Repetição e recuo
Lê os cabeçalhos do limite de taxa e aplica variação aleatória, para que os workers paralelos se comportem.
Verificação de assinatura
Sobre o corpo em bruto e em tempo constante — os dois pormenores em que se erra.
Paginação
Tratamento de cursor para históricos de eventos longos, exposto como iterador assíncrono.
Saída de emergência
Pedidos arbitrários com o mesmo comportamento de autenticação e repetição das chamadas tipadas.
Versionamento previsível
A major acompanha a versão da API; a minor acrescenta, nunca redefine.
Respostas
Perguntas frequentes
O que fazem os SDK além de encapsular HTTP?
Três coisas que vale a pena ter: tipos gerados a partir do mesmo esquema contra o qual a API valida, para que um campo errado seja um erro de compilação e não um 400; repetição e backoff que respeitem os cabeçalhos de limite de taxa; e verificação da assinatura dos webhooks, fácil de implementar subtilmente mal se calcular o hash de um corpo reserializado em vez do corpo bruto.
Posso continuar a fazer pedidos em bruto?
Sim, e os clientes foram feitos para o permitir. Todos expõem uma saída de emergência que envia um pedido arbitrário com a mesma autenticação e o mesmo comportamento de repetição. Um SDK que o obriga a passar pelas suas abstrações é um SDK contra o qual vai lutar assim que precisar de algo que ele não previu.
Que relação existe entre as versões do SDK e as da API?
A versão maior acompanha a versão da API, pelo que um cliente v1 fala com /v1. As versões menores acrescentam pontos de extremidade e campos à medida que a API cresce. Um cliente não muda de comportamento em silêncio dentro de uma versão maior — surgem campos novos, os existentes não mudam de significado.
Que linguagem devemos usar para o pipeline de emissão?
Aquela que a sua equipa de operações já usa. A via de emissão é uma tarefa agendada que fala com o seu PLM e connosco; não é sensível ao desempenho e será mantida por quem mantém as suas outras integrações. Escolher uma linguagem que ninguém aí domina é o erro evitável mais comum.
Os clientes são de código aberto?
Os clientes são gerados a partir de um esquema publicado, e o código gerado é legível e incorporável. Se tiver de fazer um fork para cumprir uma política interna, nada no protocolo depende do nosso cliente — cada payload segue normas GS1 ou W3C que poderia implementar diretamente.
Next step
Comece na linguagem que a sua equipa já utiliza
O pipeline de emissão será mantido por quem mantém as suas outras integrações. Otimize para isso, não para a novidade.