API pubblica + SDK + widget di embed
Quattro SDK first-party su un'API REST versionata. Paginazione a cursore, header Idempotency-Key, firma webhook HMAC, helper async-iterator, errori tipizzati. I tasselli di developer-experience che dovrebbero esserci — non ripensamenti.
I quattro SDK
@nexbasira/node
Server-side. Tipizzato sullo schema OpenAPI; async iterator per liste paginate; constructEvent(body, sig, secret) per la verifica dei webhook. Zero dipendenze a runtime oltre alla fetch globale.
nexbasira (PyPI)
Server-side. Modelli Pydantic v2 generati dallo schema. I client sync + async condividono la stessa superficie; la verifica dei webhook vive in WebhookSigner.verify(body, sig, secret).
@nexbasira/react
Hook + componenti per la superficie dell'operatore. <CertivisioSessionView /> renderizza la UI in sessione con branding, prove e chat. Integrala nella tua app React esistente — nessun redirect a portale.
Widget iframe
<script src=".../nb-embed.js"> + un div — l'integrazione a minor attrito. Per i team ops che gestiscono la UI dell'operatore da uno stack non-React. Il branding viene ereditato dalla pagina che fa l'embed tramite postMessage.
Costruito sulla spec OpenAPI
Gli SDK Node + Python sono generati dallo stesso schema OpenAPI 3.1 filtrato che pubblichiamo su app.nexbasira.com/api/public-schema/ — quindi se vuoi saltare l'SDK e generare il tuo client tipizzato in Go o Rust, puoi:
# 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.pyLa superficie ergonomica scritta a mano (errori tipizzati, async iterator, verifica webhook) va sopra quei tipi generati. Non devi scegliere tra "client tipizzato veloce" e "bella DX" — arrivano entrambi.
Convenzioni REST, rese noiose di proposito
| Convenzione | Perché |
|---|---|
| Paginazione a cursore | Stabile sotto scritture concorrenti. next_cursor nella risposta; ripassalo come ?cursor=…. |
Header Idempotency-Key | Invia un UUID; riprova al timeout; il server restituisce comunque la risposta originale. |
| Webhook HMAC-SHA256 | NB-Signature: t=…,v1=…. Gli SDK forniscono una verifica in una riga; finestra di replay di 5 minuti. |
| Prefisso URL versionato | /api/v1/public/. I breaking change passano a /v2/ con 12 mesi di sovrapposizione. |
| Credenziali con scope | Ogni credenziale porta scope espliciti (sessions:write, evidence:read, …). Ruotala senza perdere un tenant. |
| Envelope di errore tipizzato | Stessa forma per ogni endpoint. code, detail, retry_after_seconds quando pertinente. |
Promessa di stabilità
I cambiamenti additivi — nuovi campi opzionali, nuovi endpoint, nuovi tipi di evento webhook — arrivano sul posto; gli SDK trattano i campi sconosciuti come forward-compatible. I breaking change passano a un nuovo prefisso URL e si sovrappongono alla versione precedente per almeno 12 mesi. Non ti sveglierai con una migrazione da verde a rosso un martedì mattina.
Parti dall'avvio rapido
Crea una sessione, genera un invito sul campo, verifica un webhook — in meno di 5 minuti. curl + Node + Python copia-incolla nella stessa pagina.