APIs y Eventos
Contratos técnicos, semántica de eventos y patrones de robustez.
explanation • updated 2026-03-15
Qué resuelve esta sección
Define cómo construir integraciones previsibles en un modelo webhook-first, reduciendo divergencias entre estados temporales y estado final.
Principios de contrato
- Las operaciones mutables deben usar idempotencia.
- Los eventos son la fuente final de verdad operacional.
- Versionado y naming deben ser explícitos por dominio.
Ruta recomendada
11) Leer contratos base
Empieza por API essentials.22) Definir semántica de eventos
Aplica Convenciones de eventos.33) Cerrar seguridad de ejecución
Valida Autenticación e idempotencia.44) Formalizar racional arquitectural
Documenta trade-offs en Arquitectura webhook-first.
Criterios de calidad de integración
| Criterio | Objetivo operacional |
|---|---|
| Procesamiento duplicado | 0 efectos laterales duplicados |
| Éxito de reintentos | 100% con backoff acotado |
| Eventos sin schema | 0 en producción |
| Errores 5xx persistentes | Sin backlog fuera de la ventana SLO |
Empieza aquí
Fundamentos de la API
Headers, autenticación y patrones de respuesta.
Convenciones de eventos
Nombres, idempotencia y versionado.
Arquitectura webhook-first
Por qué el modelo es event-driven.
Autenticación e idempotencia
Scopes, retries y garantías de ejecución única.
API reference
Mapa de grupos de endpoints de Beacon.
API de Billing
Checkout, suscripciones y portal.
API de Stripe Connect
Onboarding, refresh y return flows.
API de Webhooks
Ingesta, idempotencia y replay.
API Fiscal
Documentos, conciliación y setup-state.
API de Observabilidad
Health, métricas y alertas operativas.
Especificación OpenAPI
Spec parcial lista para evolucionar a Scalar/Redoc.