SDKs
Schlanke Clients und eine Ausstiegsluke, die wirklich funktioniert
Typen aus demselben Schema, gegen das die API validiert, Retries, die die Rate-Header respektieren, und eine Signaturprüfung, die Sie sonst subtil falsch umsetzen würden. Alles Weitere ist nur einen Roh-Request entfernt.
- Typisiert aus
- Das API-Schema
- Hauptversion
- Folgt /v1
- Rohanfragen
- Immer verfügbar
Definition
Was bringt Ihnen eine Client-Bibliothek für die Pass-API?
Typen, generiert aus dem Schema, gegen das die API validiert, sodass ein falsches Feld zur Compile-Zeit fehlschlägt statt als Laufzeitfehler. Retry und Backoff, die die Rate-Limit-Header respektieren. Webhook-Signaturprüfung über den rohen Body. Und eine Ausstiegsluke für Anfragen, die der Client nicht abbildet.
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
Was verfügbar ist
| 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 |
Gestalt
Wie die Nutzung aussieht
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 });Was sie übernehmen
Die Teile, die Sie besser nicht selbst schreiben
Generierte Typen
Aus demselben Schema, gegen das die API validiert, sodass beide nicht auseinanderlaufen können.
Wiederholung und Backoff
Liest die Ratenbegrenzungs-Header und wendet Jitter an, damit parallele Worker sich benehmen.
Signaturprüfung
Über den Rohkörper, in konstanter Zeit — die beiden Details, die man falsch macht.
Paginierung
Cursor-Handhabung für lange Ereignishistorien, bereitgestellt als asynchroner Iterator.
Notausgang
Beliebige Anfragen mit demselben Auth- und Wiederholungsverhalten wie die typisierten Aufrufe.
Vorhersehbare Versionierung
Major folgt der API-Version; Minor ergänzt, definiert nie neu.
Antworten
Häufig gestellte Fragen
Was leisten die SDKs über das Kapseln von HTTP hinaus?
Drei Dinge lohnen sich: Typen, die aus demselben Schema generiert werden, gegen das die API validiert, sodass ein falsches Feld ein Compile-Fehler ist statt eines 400; Retry und Backoff, die die Rate-Limit-Header respektieren; und die Verifizierung von Webhook-Signaturen, die man leicht subtil falsch umsetzt, indem man einen neu serialisierten statt den rohen Body hasht.
Kann ich weiterhin Rohanfragen stellen?
Ja, und die Clients sind dafür gebaut. Jeder von ihnen bietet eine Ausstiegsluke, die eine beliebige Anfrage mit derselben Authentifizierung und demselben Retry-Verhalten sendet. Ein SDK, das Sie durch seine Abstraktionen zwingt, ist eines, gegen das Sie beim ersten unvorhergesehenen Bedarf ankämpfen.
Wie verhalten sich SDK-Versionen zu API-Versionen?
Die Hauptversion folgt der API-Version, ein v1-Client spricht also mit /v1. Nebenversionen ergänzen Endpunkte und Felder, während die API wächst. Ein Client ändert sein Verhalten innerhalb einer Hauptversion nicht stillschweigend — neue Felder kommen hinzu, bestehende ändern ihre Bedeutung nicht.
Welche Sprache sollten wir für die Ausstellungs-Pipeline wählen?
Die, die Ihr Ops-Team ohnehin betreibt. Der Ausstellungspfad ist ein geplanter Job, der mit Ihrem PLM und mit uns spricht; er ist nicht performancekritisch und wird von denselben Leuten gepflegt, die Ihre übrigen Integrationen pflegen. Eine Sprache zu wählen, die dort niemand kennt, ist hier der häufigste vermeidbare Fehler.
Sind die Clients Open Source?
Die Clients werden aus einem veröffentlichten Schema generiert, und der generierte Quellcode ist lesbar und einbindbar. Müssen Sie einen forken, um eine interne Richtlinie zu erfüllen, hängt nichts am Übertragungsprotokoll von unserem Client — jede Nutzlast folgt GS1- oder W3C-Standards, die Sie direkt umsetzen könnten.
Next step
In der Sprache beginnen, die Ihr Team ohnehin betreibt
Die Ausstellungs-Pipeline wird von denselben Leuten gepflegt, die auch Ihre übrigen Integrationen pflegen. Optimieren Sie dafür, nicht für Neuartigkeit.