SDKs
Des clients légers, et une porte de sortie qui fonctionne vraiment
Des types issus du schéma même contre lequel l’API valide, des reprises qui respectent les en-têtes de débit, et une vérification de signature que vous implémenteriez sinon de travers. Tout le reste est à une requête brute de distance.
- Typé à partir de
- Le schéma de l’API
- Version majeure
- Suit /v1
- Requêtes brutes
- Toujours disponible
Definition
Que vous apporte une bibliothèque cliente pour l’API passeport ?
Des types générés depuis le schéma contre lequel l’API valide, de sorte qu’un champ erroné échoue à la compilation plutôt qu’à l’exécution. Des reprises et un backoff qui respectent les en-têtes de limitation de débit. La vérification de signature des webhooks sur le corps brut. Et une porte de sortie pour les requêtes que le client ne modélise pas.
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.
Clients
Ce qui est 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 |
Forme
À quoi ressemble son utilisation
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 });Ce qu’ils prennent en charge
Ce qu’il vaut mieux ne pas écrire soi-même
Types générés
À partir du schéma même contre lequel l’API valide, si bien que les deux ne peuvent pas diverger.
Reprise et temporisation
Lit les en-têtes de limitation et applique une gigue, pour que les workers parallèles se tiennent.
Vérification de signature
Sur le corps brut, en temps constant — les deux détails que l’on rate.
Pagination
Gestion du curseur pour les longs historiques d’événements, exposée sous forme d’itérateur asynchrone.
Issue de secours
Des requêtes arbitraires avec le même comportement d’authentification et de reprise que les appels typés.
Versionnement prévisible
La majeure suit la version de l’API ; la mineure ajoute, ne redéfinit jamais.
Réponses
Questions fréquentes
Que font les SDK au-delà d’envelopper HTTP ?
Trois choses valent la peine : des types générés depuis le schéma même contre lequel l’API valide, de sorte qu’un champ erroné soit une erreur de compilation plutôt qu’un 400 ; des reprises et un backoff qui respectent les en-têtes de limitation de débit ; et la vérification de signature des webhooks, qu’il est facile d’implémenter subtilement de travers en hachant un corps resérialisé au lieu du corps brut.
Puis-je encore faire des requêtes brutes ?
Oui, et les clients sont conçus pour le permettre. Chacun expose une porte de sortie qui envoie une requête arbitraire avec la même authentification et le même comportement de reprise. Un SDK qui vous force à passer par ses abstractions est un SDK contre lequel vous lutterez dès le premier besoin qu’il n’avait pas anticipé.
Quel est le lien entre les versions du SDK et celles de l’API ?
La version majeure suit la version de l’API : un client v1 parle donc à /v1. Les versions mineures ajoutent des points de terminaison et des champs à mesure que l’API grandit. Un client ne verra pas son comportement changer en silence au sein d’une version majeure — de nouveaux champs apparaissent, les champs existants ne changent pas de sens.
Quel langage utiliser pour le pipeline d’émission ?
Celui que votre équipe ops fait déjà tourner. Le chemin d’émission est une tâche planifiée qui parle à votre PLM et à nous ; il n’est pas sensible aux performances et sera maintenu par ceux qui maintiennent vos autres intégrations. Choisir un langage que personne là-bas ne connaît est ici l’erreur évitable la plus fréquente.
Les clients sont-ils open source ?
Les clients sont générés depuis un schéma publié, et le code généré est lisible et intégrable. Si vous devez en forker un pour satisfaire une politique interne, rien dans le protocole ne dépend de notre client — chaque charge utile suit des standards GS1 ou W3C que vous pourriez implémenter directement.
Next step
Commencer dans le langage que votre équipe exploite déjà
Le pipeline d’émission sera maintenu par celui qui maintient vos autres intégrations. Optimisez pour cela, pas pour la nouveauté.