Para desarrolladores y agentes de IA

La API y el MCP de BDC AI

Contactos, conversaciones, campañas y plantillas de tu organización, con la misma autenticación y los mismos límites tanto si los llama tu código como si los llama un agente de IA.

Empieza en 5 minutos

1. Crea una llave de API
En Ajustes, Integraciones, API y agentes (/settings/canales/api) crea una llave. El valor completo (bdc_live_…) se muestra una sola vez: guárdalo, porque después solo verás el key_hint.
2. Confirma la organización
Con la llave en Authorization: Bearer, cualquier request confirma a qué organización pertenece.
```
curl https://bdcai.com/api/v1/org \
  -H "Authorization: Bearer bdc_live_…"
```
3. Lee tus contactos
Listado paginado por cursor: data[] más next_cursor, nunca un arreglo suelto.
```
curl "https://bdcai.com/api/v1/contacts?limit=5" \
  -H "Authorization: Bearer bdc_live_…"
```

4. Inicia una conversación

conversations.start es síncrona: responde 201 con la conversación y el primer mensaje ya enviado. Las operaciones que crean algo llevan Idempotency-Key (UUID); un reintento con la misma llave y el mismo cuerpo re-sirve la respuesta original en vez de duplicar el envío.

curl -X POST https://bdcai.com/api/v1/conversations \
  -H "Authorization: Bearer bdc_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "dealership_id": "…",
    "phone": "+5218110000000",
    "first_name": "María",
    "contact_type": "venta",
    "template": {
      "name": "primer_contacto",
      "language": "es_MX"
    }
  }'

Conéctalo a tu agente

Todo lo de arriba también existe como servidor MCP (Model Context Protocol) en bdcai.com/mcp: las mismas 22 operaciones, expuestas como tools que un agente de IA puede llamar directo, con la misma autenticación y los mismos límites.

Ver las tres formas de conectar un agente

Cómo se comporta la 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.

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.

{
  "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.

Scopes disponibles

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)

Referencia completa

Las 22 operaciones del contrato público, con parámetros, cuerpos y respuestas exactas, en un explorador interactivo generado desde nuestro propio OpenAPI 3.1, siempre al día con el código.

Abrir la referencia interactiva openapi.json