Öffentliche API + SDKs + Embed-Widget
Vier hauseigene SDKs über einer versionierten REST-API. Cursor-Paginierung, Idempotency-Key-Header, HMAC-Webhook-Signierung, Async-Iterator-Helper, typisierte Fehler. Die Developer-Experience-Bausteine, die dabei sein sollten — keine nachträglichen Gedanken.
Die vier SDKs
@nexbasira/node
Serverseitig. Typisiert gegen das OpenAPI-Schema; Async-Iteratoren für paginierte Listen; constructEvent(body, sig, secret) für die Webhook-Verifikation. Keinerlei Laufzeitabhängigkeiten außer dem globalen fetch.
nexbasira (PyPI)
Serverseitig. Pydantic-v2-Modelle, aus dem Schema generiert. Sync- + Async-Clients teilen dieselbe Oberfläche; die Webhook-Verifikation liegt bei WebhookSigner.verify(body, sig, secret).
@nexbasira/react
Hooks + Komponenten für die Operator-Oberfläche. <CertivisioSessionView /> rendert die In-Sitzung-UI mit Branding, Beweisen und Chat. Fügen Sie es in Ihre bestehende React-App ein — keine Portal-Weiterleitung.
iframe-Widget
<script src=".../nb-embed.js"> + ein div — die reibungsärmste Integration. Für Ops-Teams, die die Operator-UI aus einem Nicht-React-Stack betreiben. Das Branding wird von der einbettenden Seite per postMessage übernommen.
Auf der OpenAPI-Spezifikation aufgebaut
Die Node- + Python-SDKs werden aus demselben gefilterten OpenAPI-3.1-Schema generiert, das wir unter app.nexbasira.com/api/public-schema/ veröffentlichen — wenn Sie also das SDK überspringen und Ihren eigenen typisierten Client in Go oder Rust generieren möchten, können Sie das:
# Node typed client
npx openapi-typescript https://app.nexbasira.com/api/public-schema/ -o src/nb-types.ts
# Python typed models
datamodel-codegen \
--url https://app.nexbasira.com/api/public-schema/ \
--input-file-type openapi \
--output-model-type pydantic_v2.BaseModel \
--output cvp_models.pyDie handgeschriebene ergonomische Oberfläche (typisierte Fehler, Async-Iteratoren, Webhook-Verifikation) setzt auf diesen generierten Typen auf. Sie wählen nicht zwischen „schnellem typisiertem Client“ und „guter DX“ — beides ist dabei.
REST-Konventionen, absichtlich langweilig gehalten
| Konvention | Warum |
|---|---|
| Cursor-Paginierung | Stabil bei gleichzeitigen Schreibvorgängen. next_cursor in der Antwort; geben Sie ihn als ?cursor=… zurück. |
Idempotency-Key-Header | Senden Sie eine UUID; wiederholen Sie bei Timeout; der Server gibt in beiden Fällen die ursprüngliche Antwort zurück. |
| HMAC-SHA256-Webhooks | NB-Signature: t=…,v1=…. SDKs liefern eine Einzeiler-Verifikation; 5-Min-Replay-Fenster. |
| Versioniertes URL-Präfix | /api/v1/public/. Breaking Changes wandern nach /v2/ mit 12 Monaten Überlappung. |
| Scope-gebundene Credentials | Jedes Credential trägt explizite Scopes (sessions:write, evidence:read, …). Rotieren, ohne einen Tenant zu verlieren. |
| Typisierte Fehler-Envelope | Gleiche Struktur bei jedem Endpunkt. code, detail, retry_after_seconds sofern relevant. |
Stabilitätsversprechen
Additive Änderungen — neue optionale Felder, neue Endpunkte, neue Webhook-Event-Typen — werden am selben Ort ausgeliefert; die SDKs behandeln unbekannte Felder als vorwärtskompatibel. Breaking Changes wandern auf ein neues URL-Präfix und überlappen mindestens 12 Monate lang mit der Vorgängerversion. Sie wachen nicht an einem Dienstagmorgen zu einer Grün-auf-Rot-Migration auf.
Beginnen Sie mit dem Schnellstart
Erstellen Sie eine Sitzung, prägen Sie eine Feld-Einladung, verifizieren Sie einen Webhook — in unter 5 Minuten. Copy-paste-fähige curl- + Node- + Python-Beispiele auf derselben Seite.