API pública + SDKs + widget de embed
Quatro SDKs de primeira parte sobre uma API REST versionada. Paginação por cursor, cabeçalhos Idempotency-Key, assinatura HMAC de webhooks, helpers de iterador assíncrono, erros tipados. As peças de experiência de developer que deveriam estar presentes — não uma reflexão tardia.
Os quatro SDKs
@nexbasira/node
Do lado do servidor. Tipado contra o esquema OpenAPI; iteradores assíncronos para listas paginadas; constructEvent(body, sig, secret) para verificação de webhooks. Zero dependências em runtime além do fetch global.
nexbasira (PyPI)
Do lado do servidor. Modelos Pydantic v2 gerados a partir do esquema. Os clientes síncrono + assíncrono partilham a mesma superfície; a verificação de webhooks vive em WebhookSigner.verify(body, sig, secret).
@nexbasira/react
Hooks + componentes para a superfície do operador. <CertivisioSessionView /> renderiza a interface em sessão com branding, provas e chat. Encaixe na sua app React existente — sem redirecionamento para portal.
Widget em iframe
<script src=".../nb-embed.js"> + uma div — a integração de menor fricção. Para equipas de operações que correm a interface do operador a partir de uma stack não-React. O branding é herdado da página que faz o embed via postMessage.
Construído sobre a especificação OpenAPI
Os SDKs de Node + Python são gerados a partir do mesmo esquema OpenAPI 3.1 filtrado que publicamos em app.nexbasira.com/api/public-schema/ — por isso, se quiser saltar o SDK e gerar o seu próprio cliente tipado em Go ou Rust, pode:
# 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.pyA superfície ergonómica escrita à mão (erros tipados, iteradores assíncronos, verificação de webhooks) vai por cima desses tipos gerados. Não está a escolher entre «cliente tipado rápido» e «bom DX» — ambos vêm incluídos.
Convenções REST, deliberadamente aborrecidas
| Convenção | Porquê |
|---|---|
| Paginação por cursor | Estável sob escritas concorrentes. next_cursor na resposta; devolva-o como ?cursor=…. |
Cabeçalho Idempotency-Key | Envie um UUID; repita em caso de timeout; o servidor devolve a resposta original de qualquer forma. |
| Webhooks HMAC-SHA256 | NB-Signature: t=…,v1=…. Os SDKs incluem uma verificação de uma linha; janela de replay de 5 min. |
| Prefixo de URL versionado | /api/v1/public/. As alterações disruptivas passam para /v2/ com 12 meses de sobreposição. |
| Credenciais restringidas por âmbito | Cada credencial transporta âmbitos explícitos (sessions:write, evidence:read, …). Rode sem perder um tenant. |
| Envelope de erro tipado | O mesmo formato em cada endpoint. code, detail, retry_after_seconds quando relevante. |
Promessa de estabilidade
As alterações aditivas — novos campos opcionais, novos endpoints, novos tipos de evento de webhook — entram no mesmo sítio; os SDKs tratam os campos desconhecidos como compatíveis para a frente. As alterações disruptivas passam para um novo prefixo de URL e sobrepõem-se à versão anterior durante pelo menos 12 meses. Não vai acordar com uma migração de verde para vermelho numa manhã de terça-feira.
Comece pelo início rápido
Crie uma sessão, emita um convite de campo, verifique um webhook — em menos de 5 minutos. Copiar-e-colar curl + Node + Python na mesma página.