API pública + SDK + widget de incrustación
Cuatro SDK propios sobre una API REST versionada. Paginación por cursor, cabeceras Idempotency-Key, firma HMAC de webhooks, ayudantes de iterador asíncrono, errores tipados. Las piezas de experiencia de desarrollador que deberían estar ahí, no ideas de última hora.
Los cuatro SDK
@nexbasira/node
Del lado del servidor. Tipado contra el esquema OpenAPI; iteradores asíncronos para listas paginadas; constructEvent(body, sig, secret) para verificar webhooks. Cero dependencias de tiempo de ejecución más allá del fetch global.
nexbasira (PyPI)
Del lado del servidor. Modelos Pydantic v2 generados a partir del esquema. Los clientes sync + async comparten la misma superficie; la verificación de webhooks vive en WebhookSigner.verify(body, sig, secret).
@nexbasira/react
Hooks + componentes para la superficie del operador. <CertivisioSessionView /> renderiza la interfaz en sesión con marca, pruebas y chat. Intégrelo en su aplicación React existente, sin redirección a un portal.
Widget iframe
<script src=".../nb-embed.js"> + un div: la integración de menor fricción. Para equipos de operaciones que ejecutan la interfaz del operador desde un stack no basado en React. La marca se hereda de la página anfitriona mediante postMessage.
Construido sobre la especificación OpenAPI
Los SDK de Node + Python se generan a partir del mismo esquema OpenAPI 3.1 filtrado que publicamos en app.nexbasira.com/api/public-schema/, de modo que si quiere prescindir del SDK y generar su propio cliente tipado en Go o Rust, puede hacerlo:
# 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 ergonómica escrita a mano (errores tipados, iteradores asíncronos, verificación de webhooks) se apoya sobre esos tipos generados. No tiene que elegir entre «cliente tipado rápido» y «buena DX»: ambos se entregan.
Convenciones REST, aburridas a propósito
| Convención | Por qué |
|---|---|
| Paginación por cursor | Estable bajo escrituras concurrentes. next_cursor en la respuesta; devuélvalo como ?cursor=…. |
Cabecera Idempotency-Key | Envíe un UUID; reintente al agotarse el tiempo; el servidor devuelve la respuesta original de todos modos. |
| Webhooks HMAC-SHA256 | NB-Signature: t=…,v1=…. Los SDK incluyen una verificación en una línea; ventana de reenvío de 5 min. |
| Prefijo de URL versionado | /api/v1/public/. Los cambios que rompen compatibilidad pasan a /v2/ con 12 meses de solapamiento. |
| Credenciales con ámbitos restringidos | Cada credencial lleva ámbitos explícitos (sessions:write, evidence:read, …). Rótela sin perder un tenant. |
| Sobre de error tipado | La misma forma en cada endpoint. code, detail, retry_after_seconds cuando corresponda. |
Promesa de estabilidad
Los cambios aditivos (nuevos campos opcionales, nuevos endpoints, nuevos tipos de evento de webhook) se entregan en su sitio; los SDK tratan los campos desconocidos como compatibles hacia delante. Los cambios que rompen compatibilidad pasan a un nuevo prefijo de URL y se solapan con la versión anterior durante al menos 12 meses. No se despertará con una migración de verde a rojo un martes por la mañana.
Empiece con el inicio rápido
Cree una sesión, genere una invitación de campo, verifique un webhook: en menos de 5 minutos. Copie y pegue curl + Node + Python en la misma página.