OpenAPI 3.1. Standard Webhooks. RFC 9331.
Todo lo documentado aquí existe en producción hoy. La misma especificación que servimos en /api/openapi alimenta Scalar, Postman, clientes generados con openapi-typescript y este sitio. Sin claims que no podamos sostener.
Base URL: https://bignos.app/api/v1 · genera una key en Admin · API Keys.
Referencia completa abajo — auth, webhooks, rate-limits, idempotencia, errores, versionado, OpenAPI y modelo ROI.
Toda llamada server-to-server usa un API Key con prefijo bi_. Se emite desde Admin · API Keys y se envía en el header Authorization: Bearer bi_<key>. Las claves se hashean con SHA-256 antes de guardarse — nunca las tenemos ni podemos recuperar en claro.
Los requests navegador→servidor usan cookie de sesión (NextAuth) más CSRF double-submit. Los endpoints SCIM 2.0 viven en /api/scim/v2 con el mismo esquema Bearer.
Implementamos el estándar Standard Webhooks. Cada entrega incluye webhook-id, webhook-timestamp y webhook-signature (HMAC-SHA256 en base64, prefijo v1,).
signed = `${id}.${timestamp}.${body}`
signature = "v1," + base64(hmac_sha256(secret, signed))Los reintentos usan backoff exponencial hasta 5 veces. Rechaza cualquier timestamp fuera de ±5 min para evitar replay. Los logs de entrega viven en /admin · Webhooks.
Por defecto: 120 req/min por IP, 10 req/min en endpoints de autenticación. Los cupos vienen en los headers RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset. Un 429 incluye Retry-After en segundos. No hay crédito de burst en auth.
Los POST que crean recursos aceptan el header Idempotency-Key. Los reintentos con la misma key dentro de 24 h devuelven el mismo cuerpo y status original. Usa un UUIDv4 nuevo por operación de negocio, no por reintento.
Todas las respuestas 4xx/5xx comparten el mismo envelope JSON. El campo error es una clave corta legible para máquina; el status HTTP indica la categoría.
{ "error": "invalid_idempotency_key" }La mayor actual es v1, GA desde 2025-11-01. Los breaking changes entran solo en una nueva mayor. No rompemos formas de respuesta en silencio.
Los endpoints marcados para retiro devuelven Deprecation: <date>, Sunset: <date> y Link: <replacement>; rel="successor-version" (RFC 8594).
Descarga el spec completo en JSON OpenAPI 3.1. Compatible con Scalar, Swagger UI, Postman, Stoplight, Insomnia, HTTPie y clientes generados con openapi-typescript.
curl https://bignos.app/api/openapi -o openapi.json npx @scalar/cli reference openapi.json npx openapi-typescript openapi.json -o src/types/api.ts
La calculadora pública usa la misma fórmula que el panel de equipo: recoveredHours = sessionsMinutes × observedLift × residualFactor ÷ 60, con effectSizeCap = 0.35 y residualFactor = 2.0. Supuestos y referencias a literatura (Zeidan 2010, Basso 2019) viven en src/lib/roi.js — reportado como estimación, nunca como retorno garantizado.
Genera una key en minutos, ejecuta el quickstart contra tu propio entorno, y escribe webhooks firmados antes del café.