SDKs
Client leggeri e una via d’uscita che funziona davvero
Tipi generati dallo stesso schema su cui l’API valida, retry che rispettano gli header di frequenza e verifica della firma che altrimenti implementereste in modo sottilmente sbagliato. Tutto il resto è a una richiesta grezza di distanza.
- Tipizzato da
- Lo schema dell’API
- Versione major
- Segue /v1
- Richieste grezze
- Sempre disponibile
Definition
Che cosa vi dà una libreria client per l’API dei passaporti?
Tipi generati dallo schema su cui l’API valida, così che un campo sbagliato fallisca in compilazione anziché come errore a runtime. Retry e backoff che rispettano gli header del limite di frequenza. Verifica della firma dei webhook sul body grezzo. E una via d’uscita per le richieste che il client non modella.
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.
Client
Che cosa è disponibile
| 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
Com’è usarne 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 });Di che cosa si occupano
Le parti che conviene non scrivere da soli
Tipi generati
Dallo stesso schema con cui l’API valida, così i due non possono divergere.
Ritentativo e backoff
Legge gli header del limite di frequenza e applica jitter, così i worker paralleli si comportano bene.
Verifica della firma
Sul corpo grezzo, a tempo costante: i due dettagli che si sbagliano più spesso.
Paginazione
Gestione del cursore per storie di eventi lunghe, esposta come iteratore asincrono.
Via d’uscita
Richieste arbitrarie con lo stesso comportamento di autenticazione e ritentativo delle chiamate tipizzate.
Versionamento prevedibile
La major segue la versione dell’API; la minor aggiunge, non ridefinisce mai.
Risposte
Domande frequenti
Che cosa fanno gli SDK oltre a incapsulare HTTP?
Tre cose che vale la pena avere: tipi generati dallo stesso schema su cui l’API valida, così che un campo sbagliato sia un errore di compilazione anziché un 400; retry e backoff che rispettino gli header del limite di frequenza; e la verifica della firma dei webhook, facile da implementare in modo sottilmente errato calcolando l’hash di un body riserializzato invece di quello grezzo.
Posso ancora fare richieste grezze?
Sì, e i client sono costruiti per permetterlo. Ognuno espone una via d’uscita che invia una richiesta arbitraria con la stessa autenticazione e lo stesso comportamento di retry. Un SDK che vi obbliga a passare per le sue astrazioni è un SDK contro cui combatterete la prima volta che vi servirà qualcosa che non aveva previsto.
Che rapporto c’è tra le versioni dell’SDK e quelle dell’API?
La versione maggiore segue la versione dell’API, quindi un client v1 parla con /v1. Le versioni minori aggiungono endpoint e campi man mano che l’API cresce. Un client non cambierà comportamento in silenzio all’interno di una versione maggiore: compaiono nuovi campi, quelli esistenti non cambiano significato.
Quale linguaggio dovremmo usare per la pipeline di emissione?
Quello che il vostro team ops già gestisce. Il percorso di emissione è un job pianificato che parla con il vostro PLM e con noi; non è sensibile alle prestazioni e sarà mantenuto da chi mantiene le vostre altre integrazioni. Scegliere un linguaggio che lì nessuno conosce è l’errore evitabile più comune.
I client sono open source?
I client sono generati da uno schema pubblicato, e il sorgente generato è leggibile e incorporabile. Se devi forkarne uno per soddisfare una policy interna, nulla nel protocollo dipende dal nostro client: ogni payload segue standard GS1 o W3C che potresti implementare direttamente.
Next step
Parti dal linguaggio che il tuo team già usa
La pipeline di emissione sarà mantenuta da chi mantiene le vostre altre integrazioni. Ottimizzate per questo, non per la novità.