API publique + SDK + widget d'intégration
Quatre SDK propriétaires sur une API REST versionnée. Pagination par curseur, en-têtes Idempotency-Key, signature HMAC des webhooks, utilitaires d'itérateurs asynchrones, erreurs typées. Les éléments d'expérience développeur qui devraient être là — pas des ajouts de dernière minute.
Les quatre SDK
@nexbasira/node
Côté serveur. Typé sur le schéma OpenAPI ; itérateurs asynchrones pour les listes paginées ; constructEvent(body, sig, secret) pour la vérification des webhooks. Aucune 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 synchrones et asynchrones 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 image de marque, preuves et chat. À intégrer dans votre application React existante — sans redirection vers un portail.
Widget iframe
<script src=".../nb-embed.js"> + une div — l'intégration la moins contraignante. Pour les équipes d'exploitation qui pilotent l'interface opérateur depuis une stack non-React. L'image de marque hérite de la page hôte via postMessage.
Construit 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 en Rust, vous le pouvez :
# 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 se poser sur ces types générés. Vous n'avez pas à choisir 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 comme ?cursor=…. |
En-tête Idempotency-Key | Envoyez un UUID ; réessayez en cas de timeout ; le serveur renvoie la réponse d'origine dans tous les cas. |
| 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 incompatibles passent à /v2/ avec 12 mois de recouvrement. |
| Identifiants restreints par scope | Chaque identifiant porte des scopes explicites (sessions:write, evidence:read, …). Effectuez la rotation sans perdre un tenant. |
| Enveloppe d'erreur typée | Même forme pour 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 en amont. Les changements incompatibles passent à un nouveau préfixe d'URL et recouvrent la version précédente pendant au moins 12 mois. Vous ne vous réveillerez pas devant une migration passée du vert au rouge un mardi matin.
Commencez par le démarrage rapide
Créez une session, générez une invitation terrain, vérifiez un webhook — en moins de 5 minutes. Copier-coller curl + Node + Python sur la même page.