Veřejné API + SDK + vkládací widget
Čtyři vlastní SDK nad verzovaným REST API. Kurzorové stránkování, hlavičky Idempotency-Key, podepisování webhooků přes HMAC, pomocníci pro asynchronní iterátory, typované chyby. Prvky pro vývojářský komfort, které tam mají být — ne dodatečné nápady.
Čtyři SDK
@nexbasira/node
Serverová strana. Typováno proti schématu OpenAPI; asynchronní iterátory pro stránkované seznamy; constructEvent(body, sig, secret) pro ověření webhooku. Nulové runtime závislosti kromě globálního fetch.
nexbasira (PyPI)
Serverová strana. Modely Pydantic v2 generované ze schématu. Synchronní + asynchronní klienti sdílejí stejné rozhraní; ověření webhooku je v WebhookSigner.verify(body, sig, secret).
@nexbasira/react
Hooky + komponenty pro rozhraní operátora. <CertivisioSessionView /> vykreslí rozhraní relace s brandingem, důkazy a chatem. Vložte do své stávající React aplikace — bez přesměrování na portál.
Iframe widget
<script src=".../nb-embed.js"> + jeden div — integrace s nejnižší mírou tření. Pro provozní týmy, které spouštějí rozhraní operátora z non-React stacku. Branding se dědí z vkládající stránky přes postMessage.
Postaveno na specifikaci OpenAPI
SDK pro Node + Python jsou generovány ze stejného filtrovaného schématu OpenAPI 3.1, které publikujeme na app.nexbasira.com/api/public-schema/ — takže pokud chcete SDK přeskočit a vygenerovat si vlastního typovaného klienta v Go nebo Rustu, můžete:
# 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.pyRučně psané ergonomické rozhraní (typované chyby, asynchronní iterátory, ověření webhooku) se přidává nad tyto vygenerované typy. Nevybíráte mezi „rychlým typovaným klientem“ a „příjemným DX“ — dodává se obojí.
REST konvence, záměrně nudné
| Konvence | Proč |
|---|---|
| Kurzorové stránkování | Stabilní při souběžných zápisech. next_cursor v odpovědi; předejte jej zpět jako ?cursor=…. |
Hlavička Idempotency-Key | Pošlete UUID; opakujte při timeoutu; server v obou případech vrátí původní odpověď. |
| Webhooky HMAC-SHA256 | NB-Signature: t=…,v1=…. SDK dodávají jednořádkové ověření; 5minutové okno pro replay. |
| Verzovaný prefix URL | /api/v1/public/. Zásadní změny přecházejí na /v2/ s 12měsíčním překryvem. |
| Přihlašovací údaje s vymezeným rozsahem | Každý přihlašovací údaj nese explicitní rozsahy (sessions:write, evidence:read, …). Rotujte bez ztráty tenanta. |
| Typovaná obálka chyb | Stejný tvar u každého endpointu. code, detail, retry_after_seconds, když je to relevantní. |
Slib stability
Aditivní změny — nová volitelná pole, nové endpointy, nové typy událostí webhooku — se dodávají na místě; SDK zacházejí s neznámými poli jako dopředně kompatibilními. Zásadní změny přecházejí na nový prefix URL a překrývají se s předchozí verzí po dobu nejméně 12 měsíců. Neprobudíte se v úterý ráno do migrace ze zelené na červenou.
Začněte rychlým startem
Vytvořte relaci, vygenerujte terénní pozvánku, ověřte webhook — za méně než 5 minut. Curl + Node + Python ke zkopírování na stejné stránce.