API pública

Última actualización: agosto 2026

Esta página describe los principios de diseño y el contrato de la API pública. La referencia completa por endpoint se publica junto al SDK, generada desde el mismo contrato OpenAPI.

Principios

Contrato primero. Todo cambio en la API arranca por el contrato OpenAPI, no por el código.
OperationId inmutable. Un operationId publicado es un identificador público estable. Cambiarlo se considera un breaking change.
Versionado explícito. Los cambios breaking se publican en una versión nueva; los no-breaking se agregan sin romper clientes.
SDK generado. El SDK oficial se genera desde el contrato; el código escrito a mano queda al mínimo.

Autenticación

Token por organización y usuario, con scope y expiración configurable. El token viaja en el header Authorization: Bearer <token>. La API valida pertenencia de organización antes de ejecutar cualquier operación tenant-scoped.

Recursos principales

Recurso	Descripción
`/clients`	Clientes de la organización.
`/deals`	Oportunidades con Revenue Score y Next Best Action.
`/products`	Catálogo de productos per-org.
`/sellers`	Vendedores, tiers y reglas.
`/commissions`	Cálculos de comisiones por vendedor y período.
`/webhooks`	Suscripción a eventos de dominio.

Rate limits

Los rate limits escalan por plan. Los headers de respuesta indican el límite total, las requests restantes y la ventana de reset:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1721318400

Errores

Todas las respuestas de error tienen forma { code, requestId }. Los mensajes internos no se filtran al cliente. El requestId permite trazar el request en logs.

{
  "code": "org_context_missing",
  "requestId": "req_01HYT..."
}

Webhooks

HTTPS obligatorio, firma HMAC en el header X-RQE-Signature.
Reintentos con backoff exponencial ante 5xx.
Deduplicación por eventId.

SDK

El SDK oficial se genera desde el contrato OpenAPI. Sigue el mismo esquema de versionado que la API. Consumir la API vía SDK es el camino recomendado; consumirla vía HTTP directo también está soportado.

Compromisos de estabilidad

Los operationId publicados no cambian.
Los campos existentes no cambian de tipo ni se eliminan sin nueva versión.
Los códigos de error existentes no cambian de significado.