SDKs
Clientes ligeros y una salida de emergencia que funciona de verdad
Tipos generados a partir del mismo esquema contra el que valida la API, reintentos que respetan las cabeceras de tasa y verificación de firma que de otro modo implementaría sutilmente mal. Todo lo demás está a una petición en crudo de distancia.
- Tipado a partir de
- El esquema de la API
- Versión mayor
- Sigue a /v1
- Peticiones en crudo
- Siempre disponible
Definition
¿Qué le aporta una biblioteca cliente de la API de pasaportes?
Tipos generados a partir del esquema contra el que valida la API, de modo que un campo equivocado falle en tiempo de compilación y no como error en ejecución. Reintentos y backoff que respetan las cabeceras de límite de tasa. Verificación de firma de webhooks sobre el cuerpo en crudo. Y una salida de emergencia para las peticiones que el cliente no 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
Qué hay disponible
| 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
Cómo es usar uno
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 });De qué se encargan
Las partes que conviene no escribir uno mismo
Tipos generados
Del mismo esquema contra el que valida la API, de modo que ambos no pueden divergir.
Reintento y retroceso
Lee las cabeceras de límite de frecuencia y aplica desfase aleatorio, para que los trabajadores en paralelo se comporten.
Verificación de firma
Sobre el cuerpo en bruto y en tiempo constante: los dos detalles que se suelen fallar.
Paginación
Manejo de cursor para historiales de eventos largos, expuesto como iterador asíncrono.
Vía de escape
Peticiones arbitrarias con el mismo comportamiento de autenticación y reintento que las llamadas tipadas.
Versionado predecible
La mayor sigue a la versión de la API; la menor añade, nunca redefine.
Respuestas
Preguntas frecuentes
¿Qué hacen los SDK más allá de envolver HTTP?
Tres cosas que merece la pena tener: tipos generados a partir del mismo esquema contra el que valida la API, de modo que un campo equivocado sea un error de compilación y no un 400; reintentos y backoff que respeten las cabeceras de límite de tasa; y verificación de la firma de los webhooks, fácil de implementar sutilmente mal si se calcula el hash de un cuerpo reserializado en lugar del original.
¿Puedo seguir haciendo peticiones en crudo?
Sí, y los clientes están hechos para permitirlo. Todos exponen una salida de emergencia que envía una petición arbitraria con la misma autenticación y el mismo comportamiento de reintento. Un SDK que le obliga a pasar por sus abstracciones es un SDK contra el que peleará la primera vez que necesite algo que no previó.
¿Qué relación hay entre las versiones del SDK y las de la API?
La versión mayor sigue a la versión de la API, de modo que un cliente v1 habla con /v1. Las versiones menores añaden endpoints y campos a medida que la API crece. Un cliente no cambiará de comportamiento en silencio dentro de una versión mayor: aparecen campos nuevos, los existentes no cambian de significado.
¿Qué lenguaje deberíamos usar para el flujo de emisión?
El que su equipo de operaciones ya maneja. La vía de emisión es un trabajo programado que habla con su PLM y con nosotros; no es sensible al rendimiento y la mantendrá quien mantenga sus otras integraciones. Elegir un lenguaje que nadie allí conoce es el error evitable más común aquí.
¿Son los clientes de código abierto?
Los clientes se generan a partir de un esquema publicado, y el código generado es legible e incorporable. Si necesita bifurcar uno para cumplir una política interna, nada del protocolo depende de nuestro cliente: cada carga útil sigue estándares GS1 o W3C que usted podría implementar directamente.
Next step
Empiece en el lenguaje que su equipo ya utiliza
El proceso de emisión lo mantendrá quien mantenga el resto de sus integraciones. Optimice para eso, no para la novedad.