API para desarrolladores

Primeros pasos

La API es REST sobre HTTPS. Las peticiones y las respuestas usan application/json en UTF-8, y todas cuelgan de la misma URL base:

https://agentaibi.com/aibicore/

• Las fechas se devuelven en ISO 8601 (2026-09-01T14:03:00Z).
• Los identificadores de recurso son numéricos; los de integración son UUID.
• Los nombres de los campos van en PascalCase, tal como los devuelve la API.

Las tres formas de integrar

Antes del listado de endpoints conviene saber cuál de los tres caminos necesitas. Los dos primeros no requieren iniciar sesión: se autentican con un token propio del recurso, pensado para vivir en la configuración de tu sistema.

1. Disparar un flujo desde tu sistema

Cada flujo tiene dos identificadores propios: uno que lo identifica en la URL y otro que autentica la petición en la cabecera. Van separados a propósito, para poder rotar el token sin cambiar la URL que ya pegaste en tu sistema. Los encuentras en la configuración del flujo, dentro del panel.

POST https://agentaibi.com/aibicore/Flujo/webhook/{webhookToken}
Authorization: Bearer {webhookAuthToken}
Content-Type: application/json

{
  "nombre": "Ana Restrepo",
  "telefono": "+573001234567",
  "fecha_cita": "2026-09-04"
}

Cada campo del cuerpo entra al flujo como una variable disponible desde el nodo de inicio. La respuesta es inmediata: AIBI acepta el trabajo y sigue por su cuenta.

# 202 Accepted
{ "IDEjecucion": 4187, "message": "Ejecución iniciada" }

Si el flujo contiene un nodo de voz en tiempo real o de videollamada, la respuesta espera a que la sesión exista y te devuelve además la URL a la que enviar al usuario:

{
  "IDEjecucion": 4188,
  "sesion_url": "https://agentaibi.com/Videocallv1/...",
  "sesion_token": "3f2a91c4-...",
  "message": "Sesión creada"
}

2. Recibir en tu sistema lo que pasó

Para que AIBI avise a tu backend, añade un nodo Webhook al flujo en el punto donde quieras el aviso —normalmente después del agente— y pon ahí tu URL. AIBI enviará un POST con el contexto del flujo en ese momento:

POST https://tu-sistema.com/aibi/resultado
Content-Type: application/json

{
  "ejecucion_id": 4187,
  "detalle_id": 9032,
  "telefono": "+573001234567",
  "nombre": "Ana Restrepo",
  "datos": {
    "resultado": "contestada",
    "objetivo_logrado": "true",
    "fecha_cita": "2026-09-04"
  }
}

• datos lleva el contexto del flujo en ese punto: las variables de arranque más todo lo que los nodos anteriores hayan añadido.
• Las variables internas de control y los tokens de sesión nunca se incluyen, aunque estén en el contexto.
• Cada envío queda registrado con el código de respuesta de tu servidor, para poder revisar después qué avisos llegaron y cuáles no.
• La URL de destino debe ser pública. Se rechazan direcciones internas y de red privada.

3. Mantener tus tablas al día

Una tabla de Datos puede recibir filas desde fuera. Se activa por tabla desde el panel y, igual que los flujos, entrega dos identificadores: uno para la URL y otro para la cabecera. El token se muestra una sola vez.

POST https://agentaibi.com/aibicore/Ingesta/{publicId}
Authorization: Bearer {ingestToken}
Content-Type: application/json

{
  "modo": "upsert",
  "filas": [
    { "externalId": "SKU-1", "valores": { "sku": "SKU-1", "nombre": "Cama ortopédica", "precio": 189000, "stock": 4 } },
    { "externalId": "SKU-2", "valores": { "sku": "SKU-2", "nombre": "Collar antipulgas", "precio": 42000, "stock": 20 } }
  ]
}

Las claves de valores son los nombres de las columnas de tu tabla, tal cual. externalId es el identificador de la fila en tu sistema: es lo que hace el envío idempotente, de modo que reenviar el mismo lote actualiza en vez de duplicar.

La respuesta dice exactamente qué ocurrió con el lote:

{ "ok": true, "recibidas": 2, "creadas": 2, "actualizadas": 0,
  "borradas": 0, "rechazadas": [], "message": null }

Lo escrito queda disponible para el agente en su siguiente consulta: no hay reindexado pendiente. Y cada envío deja bitácora, consultable en GET /Datasets/{id}/ingestas.

Autenticación de la API de gestión

Para el resto de la API —crear agentes, editar flujos, consultar ejecuciones, leer el saldo— hay dos formas de autenticarse. Para una integración, usa la primera.

API key (recomendado)

Genera una clave desde el panel, en la sección de API keys, y envíala en la cabecera X-API-Key. No caduca cada pocas horas, se revoca sin tocar la contraseña de la cuenta y puede ser de solo lectura.

GET https://agentaibi.com/aibicore/Agente
X-API-Key: aibi_live_{tu_clave}

• La clave se muestra una sola vez, al crearla. Se guarda como huella criptográfica, así que no podemos volver a enseñártela: si la pierdes, se rota.
• Permisos. Al crear la clave eliges qué puede hacer. Una clave sin ningún permiso de escritura solo responde a GET; cualquier intento de crear, modificar o borrar recibe 401.
• Alcance limitado. Una API key opera sobre los datos de tu cuenta y nunca da acceso a funciones de administración de la plataforma, aunque tu usuario sea administrador.
• Se puede revocar en cualquier momento, y deja de funcionar al instante. Desactivar la cuenta también inutiliza sus claves.

Token de sesión

La alternativa es el token Bearer que devuelve el inicio de sesión. Es lo que usa el panel; para una integración es peor opción, porque obliga a guardar las credenciales de la cuenta y a renovar el token.

POST https://agentaibi.com/aibicore/Usuario/login
Content-Type: application/json

{
  "NombreUsuario": {tu_usuario},
  "Password": {tu_contraseña}
}

# Respuesta
{
  "Success": true,
  "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "Usuario": { "IDUsuario": 12, "NombreUsuario": "clinica-norte" }
}

El token dura 10 horas. Después va en cada petición:

Authorization: Bearer {token}

Códigos de estado

Los errores devuelven un cuerpo JSON con un mensaje legible:

{ "message": "Token de autorización inválido" }

Endpoints

Los recursos de la API de gestión, agrupados por área. Todos requieren el token Bearer del inicio de sesión, salvo los marcados como públicos, y operan siempre sobre los datos de la cuenta a la que pertenece el token.

Ejemplo completo

Lanzar una campaña de recordatorios desde tu backend y recoger el resultado:

# 1) Cargar los contactos del día en la tabla que lee el flujo
POST https://agentaibi.com/aibicore/Ingesta/{publicId}
Authorization: Bearer {ingestToken}

{ "modo": "reemplazar", "filas": [ /* ... */ ] }

# 2) Disparar el flujo que recorre la tabla y llama a cada uno
POST https://agentaibi.com/aibicore/Flujo/webhook/{webhookToken}
Authorization: Bearer {webhookAuthToken}

{ "campana": "recordatorios-2026-09-04" }

# 3) El nodo Webhook del flujo llama a tu servidor por cada contacto atendido,
#    y el estado global se consulta cuando quieras:
GET https://agentaibi.com/aibicore/EjecucionFlujo/{id}
Authorization: Bearer {token}

Límites de uso

Los límites que hay hoy protegen los puntos sensibles, y se aplican por dirección IP dentro de una ventana de un minuto:

Al superarlos la API responde 429. Si tu integración necesita un volumen mayor, escríbenos y lo ajustamos para tu cuenta.

Consumo de créditos

Lo que se lanza por API consume igual que lo que se lanza desde el panel: solo el tiempo de conversación. Las llamadas a la API de gestión, la ingesta de datos y los webhooks no cuestan créditos. Puedes consultar tu saldo con GET /Transaccion/saldo y el detalle de consumo con GET /Transaccion. Las tarifas vigentes están en Precios y también se pueden leer por API, sin autenticación, en GET /Transaccion/tarifas.