Publieke API + SDK's + embed-widget
Vier first-party SDK's bovenop een geversioneerde REST-API. Cursor-paginatie, Idempotency-Key-headers, HMAC-webhook-ondertekening, async-iterator-helpers, getypeerde fouten. De developer-experience-onderdelen die er horen te zijn — geen bijzaken.
De vier SDK's
@nexbasira/node
Server-side. Getypeerd tegen het OpenAPI-schema; async-iterators voor gepagineerde lijsten; constructEvent(body, sig, secret) voor webhook-verificatie. Nul runtime-afhankelijkheden buiten de globale fetch.
nexbasira (PyPI)
Server-side. Pydantic v2-modellen gegenereerd uit het schema. Sync- + async-clients delen hetzelfde oppervlak; webhook-verificatie zit op WebhookSigner.verify(body, sig, secret).
@nexbasira/react
Hooks + componenten voor het operator-oppervlak. <CertivisioSessionView /> rendert de in-sessie-UI met branding, bewijs en chat. Plaats het in uw bestaande React-app — geen portal-redirect.
Iframe-widget
<script src=".../nb-embed.js"> + een div — de integratie met de minste frictie. Voor ops-teams die de operator-UI vanuit een niet-React-stack draaien. Branding erft van de embeddende pagina via postMessage.
Gebouwd op de OpenAPI-spec
De Node- + Python-SDK's worden gegenereerd uit hetzelfde gefilterde OpenAPI 3.1-schema dat we publiceren op app.nexbasira.com/api/public-schema/ — dus als u de SDK wilt overslaan en uw eigen getypeerde client in Go of Rust wilt genereren, dan kan dat:
# 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.pyHet handgeschreven ergonomische oppervlak (getypeerde fouten, async-iterators, webhook-verificatie) komt bovenop die gegenereerde types. U kiest niet tussen "snelle getypeerde client" en "prettige DX" — beide worden geleverd.
REST-conventies, met opzet saai gemaakt
| Conventie | Waarom |
|---|---|
| Cursor-paginatie | Stabiel bij gelijktijdige schrijfbewerkingen. next_cursor in de response; geef het terug als ?cursor=…. |
Idempotency-Key-header | Stuur een UUID; opnieuw proberen bij timeout; de server retourneert hoe dan ook de oorspronkelijke response. |
| HMAC-SHA256-webhooks | NB-Signature: t=…,v1=…. SDK's leveren een one-liner-verificatie; replay-venster van 5 min. |
| Geversioneerde URL-prefix | /api/v1/public/. Breaking changes verhuizen naar /v2/ met 12 maanden overlap. |
| Scope-gebonden credentials | Elke credential draagt expliciete scopes (sessions:write, evidence:read, …). Roteer zonder een tenant te verliezen. |
| Getypeerde foutenvelope | Dezelfde vorm bij elk endpoint. code, detail, retry_after_seconds waar relevant. |
Stabiliteitsbelofte
Additieve wijzigingen — nieuwe optionele velden, nieuwe endpoints, nieuwe webhook-event-types — worden ter plekke geleverd; de SDK's behandelen onbekende velden als voorwaarts compatibel. Breaking changes verhuizen naar een nieuwe URL-prefix en overlappen minstens 12 maanden met de vorige versie. U wordt niet op een dinsdagochtend wakker met een migratie van groen naar rood.
Begin met de quickstart
Maak een sessie, genereer een velduitnodiging, verifieer een webhook — in minder dan 5 minuten. Copy-paste curl + Node + Python op dezelfde pagina.