Riferimento API

L'API pubblica NexBasira è REST + JSON, versionata sotto /api/v1/public/*. Ogni endpoint è autenticato tramite la tua coppia di credenziali cvp_pub:cvp_sec, protetto da scope e paginato a cursore dove restituisce una lista.

Base URL

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

Per le installazioni self-hosted, sostituisci l'host con il tuo. Il path è lo stesso.

Sezioni

Autenticazione — coppia di credenziali, schema di firma, catalogo degli scope
Paginazione + idempotenza — paginazione a cursore + header Idempotency-Key
Errori + rate limit — forma dell'envelope di errore, header X-RateLimit-*
Sessioni — crea, elenca, recupera, termina, invita
Prove — elenca, recupera, URL di download firmato
Lavagne — elenca per sessione
Endpoint webhook — registra / rotate-secret / test-fire
Branding — sola lettura sull'API pubblica; le modifiche via SPA
Org — metadati org in sola lettura

Schema OpenAPI

Una spec OpenAPI 3.1 filtrata (solo le operazioni contrassegnate public-api) è servita su https://app.nexbasira.com/api/public-schema/. Usala direttamente con i generatori di codice:

# 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

I nostri SDK (@nexbasira/node + nexbasira per Python) sono costruiti sopra questi tipi generati e aggiungono ergonomia scritta a mano — errori tipizzati, paginazione con async-iterator, helper di verifica dei webhook.

Stabilità dell'API

L'API pubblica segue il semver-per-namespace-URL. I breaking change vengono rilasciati sotto un nuovo prefisso (/api/v2/public/*) con almeno 12 mesi di sovrapposizione prima che la versione precedente venga ritirata. I cambiamenti additivi (nuovi campi opzionali, nuovi endpoint, nuovi tipi di evento) vengono rilasciati in loco; gli SDK trattano i campi sconosciuti come compatibili in avanti.