Cómo se comporta la API: autenticación, scopes, errores, idempotencia y límites
Las reglas comunes a todas las operaciones de la API de BDC AI: las tres formas de autenticarte, los scopes, la forma de los errores, la idempotencia, el rate limit y el request_id.
· API
Autenticación
Tres formas de credencial, según quién llama: cookie de sesión (el dashboard), Authorization: Bearer <jwt> (móvil u OAuth 2.1 de Supabase) y Authorization: Bearer bdc_live_… (llave de API con scopes). El módulo API debe estar encendido en tu organización.
Scopes
Cada ruta y cada tool MCP exige exactamente un scope. Un scope de escritura implica el de lectura equivalente (contacts:write implica contacts:read). Al crear una llave eliges solo los scopes que tu integración necesita.
| Scope | Qué permite |
|---|---|
contacts:read | Leer contactos |
contacts:write | Crear y editar contactos |
conversations:read | Leer conversaciones y mensajes |
conversations:write | Asignar, mover de etapa, notas, prender/apagar IA |
messages:send | Enviar mensajes de WhatsApp |
campaigns:read | Leer campañas y segmentos |
campaigns:write | Crear y programar campañas |
templates:read | Leer plantillas aprobadas |
ads:read | Leer campañas de Meta Ads |
ads:write | Proponer y editar campañas de Meta Ads |
ads:approve | Aprobar acciones de Meta Ads (solo usuarios admin) |
Errores
Todo error no-2xx tiene la misma forma: { error, code, details?, request_id }. Cita el request_id si necesitas escalar un caso a soporte. Un 409 con code template_paused significa que la plantilla está aprobada pero WhatsApp la pausó por calidad; se reactiva sola en unas horas, mientras tanto usa otra plantilla.
{
"error": "La plantilla no está aprobada",
"code": "template_not_approved",
"request_id": "req_…"
}Idempotencia
Las operaciones que crean o disparan algo (conversations.start, messages.send, campaigns.create, campaigns.schedule…) exigen el header Idempotency-Key con un UUID. Repetir la misma llave con el mismo cuerpo re-sirve la respuesta original (Idempotent-Replayed: true); la misma llave con un cuerpo distinto responde 422 idempotency_conflict.
Rate limit
Ventana fija por llave o por agente: 120 llamadas/minuto por defecto, 30/minuto para envío de mensajes y 10/minuto para escritura de campañas. Cada respuesta lleva RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset.
Trazabilidad
Cada respuesta lleva X-Request-Id. Guárdalo en tus logs: es el mismo id que aparece en request_id cuando algo falla, y el que soporte te va a pedir primero.
¿Te sirvió este artículo?
¿No se resolvió?
Escríbenos por WhatsApp con una captura de lo que ves: cada mensaje abre un ticket con nuestro equipo.