Publiczne API + SDK + widget do osadzania
Cztery firmowe SDK oparte na wersjonowanym REST API. Paginacja kursorowa, nagłówki Idempotency-Key, podpisywanie webhooków HMAC, helpery iteratorów asynchronicznych, typowane błędy. Elementy doświadczenia programisty, które powinny tu być — nie jako dodatek na później.
Cztery SDK
@nexbasira/node
Po stronie serwera. Typowane względem schematu OpenAPI; iteratory asynchroniczne dla list stronicowanych; constructEvent(body, sig, secret) do weryfikacji webhooków. Zero zależności runtime poza globalnym fetch.
nexbasira (PyPI)
Po stronie serwera. Modele Pydantic v2 generowane ze schematu. Klienci synchroniczny i asynchroniczny współdzielą tę samą powierzchnię; weryfikacja webhooków znajduje się w WebhookSigner.verify(body, sig, secret).
@nexbasira/react
Hooki i komponenty dla powierzchni operatora. <CertivisioSessionView /> renderuje interfejs w sesji z brandingiem, materiałem dowodowym i czatem. Wstaw do istniejącej aplikacji React — bez przekierowania do portalu.
Widget iframe
<script src=".../nb-embed.js"> + div — integracja o najniższym progu wejścia. Dla zespołów operacyjnych, które prowadzą interfejs operatora ze stosu innego niż React. Branding jest dziedziczony ze strony osadzającej za pośrednictwem postMessage.
Zbudowane na specyfikacji OpenAPI
SDK Node i Python są generowane z tego samego filtrowanego schematu OpenAPI 3.1, który publikujemy pod app.nexbasira.com/api/public-schema/ — więc jeśli chcą Państwo pominąć SDK i wygenerować własnego typowanego klienta w Go lub Rust, można to zrobić:
# 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.pyRęcznie napisana ergonomiczna powierzchnia (typowane błędy, iteratory asynchroniczne, weryfikacja webhooków) nakłada się na te wygenerowane typy. Nie trzeba wybierać między „szybkim typowanym klientem” a „dobrym DX” — dostajesz oba.
Konwencje REST, celowo nudne
| Konwencja | Dlaczego |
|---|---|
| Paginacja kursorowa | Stabilna przy równoczesnych zapisach. next_cursor w odpowiedzi; przekaż go z powrotem jako ?cursor=…. |
Nagłówek Idempotency-Key | Wyślij UUID; ponów przy przekroczeniu limitu czasu; serwer w obu przypadkach zwróci oryginalną odpowiedź. |
| Webhooki HMAC-SHA256 | NB-Signature: t=…,v1=…. SDK dostarczają jednolinijkową weryfikację; 5-minutowe okno powtórki. |
| Wersjonowany prefiks URL | /api/v1/public/. Zmiany łamiące kompatybilność przechodzą do /v2/ z 12-miesięcznym okresem nakładania. |
| Poświadczenia z ograniczonym zakresem | Każde poświadczenie niesie jawne zakresy (sessions:write, evidence:read, …). Rotuj bez utraty tenanta. |
| Typowana koperta błędu | Ten sam kształt w każdym endpoincie. code, detail, retry_after_seconds tam, gdzie ma to znaczenie. |
Obietnica stabilności
Zmiany addytywne — nowe pola opcjonalne, nowe endpointy, nowe typy zdarzeń webhooków — wchodzą w miejscu; SDK traktują nieznane pola jako kompatybilne w przód. Zmiany łamiące kompatybilność przechodzą do nowego prefiksu URL i nakładają się z poprzednią wersją przez co najmniej 12 miesięcy. Nie obudzisz się w środę rano z migracją z zielonego na czerwony.
Zacznij od szybkiego startu
Utwórz sesję, wystaw zaproszenie terenowe, zweryfikuj webhook — w niecałe 5 minut. Gotowe do skopiowania curl + Node + Python na tej samej stronie.