Referência da API

A API pública da NexBasira é REST + JSON, versionada sob /api/v1/public/*. Cada endpoint é autenticado via o seu par de credenciais cvp_pub:cvp_sec, restrito por scope e paginado por cursor sempre que devolve uma lista.

URL base

https://app.nexbasira.com/api/v1/public

Para instalações auto-alojadas, troque o host pelo seu. O caminho é o mesmo.

Secções

• Autenticação — par de credenciais, esquema de assinatura, catálogo de scopes
• Paginação + idempotência — paginação por cursor + cabeçalho Idempotency-Key
• Erros + limites de taxa — forma do envelope de erro, cabeçalhos X-RateLimit-*
• Sessões — criar, listar, obter, terminar, convidar
• Provas — listar, obter, URL de transferência assinado
• Quadros brancos — listar por sessão
• Endpoints de webhook — registar / rodar-segredo / disparo-de-teste
• Marca — apenas leitura na API pública; mutações via a SPA
• Organização — metadados da organização apenas leitura

Esquema OpenAPI

Uma especificação OpenAPI 3.1 filtrada (apenas as operações com a tag public-api) é servida em https://app.nexbasira.com/api/public-schema/. Use-a diretamente com geradores de código:

# Node typed types
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.py

Os nossos SDKs (@nexbasira/node + nexbasira para Python) são construídos sobre estes tipos gerados e acrescentam ergonomia escrita à mão por cima — erros tipados, paginação por async-iterator, helpers de verificação de webhook.

Estabilidade da API

A API pública segue semver-por-namespace-de-URL. As alterações disruptivas são lançadas sob um novo prefixo (/api/v2/public/*) com pelo menos 12 meses de sobreposição antes de a versão anterior ser retirada. As alterações aditivas (novos campos opcionais, novos endpoints, novos tipos de evento) são lançadas no local; os SDKs tratam os campos desconhecidos como compatíveis para a frente.