API publique + SDK + widget embed
Quatre SDK officiels sur une API REST versionnée. Pagination par curseur, en-têtes Idempotency-Key, signature HMAC des webhooks, helpers d'itérateur asynchrone, erreurs typées. Les éléments d'expérience développeur qui doivent y être — pas des ajouts après coup.
Les quatre SDK
@nexbasira/node
Côté serveur. Typé contre le schéma OpenAPI ; itérateurs asynchrones pour les listes paginées ; constructEvent(body, sig, secret) pour la vérification des webhooks. Zéro dépendance d'exécution au-delà du fetch global.
nexbasira (PyPI)
Côté serveur. Modèles Pydantic v2 générés à partir du schéma. Les clients synchrone + asynchrone partagent la même surface ; la vérification des webhooks se trouve dans WebhookSigner.verify(body, sig, secret).
@nexbasira/react
Hooks + composants pour la surface opérateur. <CertivisioSessionView /> affiche l'interface en session avec le branding, les preuves et le chat. Intégrez-le dans votre application React existante — sans redirection vers un portail.
Widget iframe
<script src=".../nb-embed.js"> + un div — l'intégration la plus simple. Pour les équipes ops qui exécutent l'interface opérateur depuis une stack non-React. Le branding est hérité de la page hôte via postMessage.
Bâti sur la spécification OpenAPI
Les SDK Node + Python sont générés à partir du même schéma OpenAPI 3.1 filtré que nous publions sur app.nexbasira.com/api/public-schema/ — donc si vous voulez vous passer du SDK et générer votre propre client typé en Go ou Rust, c'est possible :
# 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 surface ergonomique écrite à la main (erreurs typées, itérateurs asynchrones, vérification des webhooks) vient par-dessus ces types générés. Vous ne choisissez pas entre « client typé rapide » et « bonne DX » — les deux sont livrés.
Conventions REST, volontairement ennuyeuses
| Convention | Pourquoi |
|---|---|
| Pagination par curseur | Stable en cas d'écritures concurrentes. next_cursor dans la réponse ; renvoyez-le en ?cursor=…. |
En-tête Idempotency-Key | Envoyez un UUID ; réessayez en cas de timeout ; le serveur renvoie de toute façon la réponse d'origine. |
| Webhooks HMAC-SHA256 | NB-Signature: t=…,v1=…. Les SDK fournissent une vérification en une ligne ; fenêtre de rejeu de 5 min. |
| Préfixe d'URL versionné | /api/v1/public/. Les changements cassants passent à /v2/ avec 12 mois de chevauchement. |
| Identifiants restreints par portée | Chaque identifiant porte des portées explicites (sessions:write, evidence:read, …). Faites-les tourner sans perdre de tenant. |
| Enveloppe d'erreur typée | Même forme sur chaque endpoint. code, detail, retry_after_seconds le cas échéant. |
Promesse de stabilité
Les changements additifs — nouveaux champs optionnels, nouveaux endpoints, nouveaux types d'événements webhook — sont livrés en place ; les SDK traitent les champs inconnus comme compatibles ascendants. Les changements cassants passent à un nouveau préfixe d'URL et chevauchent la version précédente pendant au moins 12 mois. Vous ne vous réveillerez pas un mardi matin sur une migration passée au rouge.
Commencez par le démarrage rapide
Créez une session, émettez une invitation terrain, vérifiez un webhook — en moins de 5 minutes. curl + Node + Python en copier-coller sur la même page.