Asixto Gateway
Documentación de integración del Asixto Gateway
Guía para equipos de ingeniería que van a conectar sus sistemas a los agentes de IA de Asixto (chat omnicanal y llamadas telefónicas).
La integración tiene dos etapas independientes:
| Etapa | Dirección | Qué construye usted |
|---|---|---|
| 1. Servidor de herramientas | Asixto → sus sistemas | Un servidor MCP que expone sus operaciones de negocio |
| 2. API del Gateway | sus sistemas → Asixto | Llamadas a nuestra API para iniciar conversaciones y recibir eventos |
Esta documentación cubre las dos: la etapa 1 en las páginas 01 a 10, y la etapa 2 en las páginas 14 a 17 —la referencia de la API— más el contrato de los webhooks (página 11). Las dos son independientes: puede desarrollar y probar su servidor de herramientas —y su receptor de webhooks— antes de tener credenciales de la API, y puede llamar a la API sin haber publicado ningún servidor.
Solo HTTP. La API es JSON sobre HTTPS y no hay SDK que instalar ni versionar: cualquier cliente
HTTP sirve, y los ejemplos son curl para que se puedan pegar en una terminal.
Dónde se da de alta su servidor. El alta —la URL de su servidor, la credencial, la URL de su entorno de pruebas y la era de protocolo que habla (página 09)— se hace en la aplicación de Asixto. Cuando su servidor esté listo, recibe sus credenciales de acceso, registra esos cuatro datos y la certificación arranca desde ahí (página 08). No necesita ese acceso para construir: el orden recomendado es escribir el servidor, verificarlo usted mismo con la lista de la página 08 y avisarnos. Así la primera certificación pasa en la primera vuelta.
Qué es la etapa 1
En una frase: un servidor que el agente puede leer y escribir. Consulta empresa, catálogo, clientes, casos, agenda y embudo, y también abre casos, actualiza datos, agenda, reagenda, cancela y mueve oportunidades. De las 25 herramientas del catálogo de referencia, 13 son de lectura y 12 mutan su sistema.
Sus sistemas siguen siendo suyos, y el modelo de integración son tres pasos:
- Conectar. Usted publica un servidor MCP (Model Context Protocol, estándar abierto) y entrega a Asixto dos datos: la URL y una credencial.
- Instruir. En Asixto configura su agente: cómo atiende, qué prioriza, qué hacer en cada situación. Esas instrucciones llegan al agente junto con su catálogo de herramientas (página 04).
- El agente resuelve. Decide en la conversación qué herramienta llamar y con qué argumentos. Usted no programa flujos, no declara endpoints ni orquesta llamadas.
Lo único que conviene tener claro del tercer paso: el agente resuelve mientras conversa. Una instrucción del tipo «antes de cerrar, registra el resultado» se cumple dentro de la conversación; lo que ocurre después del último turno no lo decide el agente.
Lo que no hay que hacer: declarar endpoints uno por uno, mandarnos un OpenAPI para que lo revisemos, o esperar una liberación nuestra cuando usted agregue una herramienta.
┌──────────────────────┐ ┌─────────────────┐ ┌──────────────────┐
│ Su servidor MCP │ MCP │ Asixto Gateway │ │ Agente de IA │
│ (sus tools sobre su │◄──────►│ descubre, │◄──────►│ chat y llamadas │
│ backend / ERP / BD) │ HTTPS │ valida, ejecuta │ │ telefónicas │
└──────────────────────┘ └─────────────────┘ └──────────────────┘
usted Asixto AsixtoÍndice
| # | Página | Contenido |
|---|---|---|
| 01 | Quickstart | La primera hora: servidor mínimo funcionando y probado en local |
| 02 | Contrato de herramientas | Referencia: entrada, salida, anotaciones, nombres |
| 03 | Autenticación | OAuth 2.1, metadatos de recurso protegido, token rotable |
| 04 | Catálogo requerido | Qué exponer según lo que quiera que el agente resuelva |
| 05 | Garantías obligatorias | Idempotencia, propiedad, estado terminal, dato crítico |
| 06 | Errores | Forma del error y códigos que interpreta el agente |
| 07 | Límites y rendimiento | Latencia, tamaños, paginación, cuotas |
| 08 | Certificación | Comprobaciones automáticas antes de producción |
| 09 | Versionado | Revisión del protocolo y política de cambios |
| 10 | Operación y soporte | Reintentos, concurrencia, caídas, pruebas con agente real, trazas y contacto |
| 11 | Webhooks | Etapa 2: firma, ventana anti-replay, deduplicación, catálogo de eventos y reintentos de entrega |
| 12 | Precios | Lo que consume cada operación en créditos, los mínimos facturados y por qué el entorno de pruebas cuesta lo mismo |
| 13 | Datos, retención y subencargados | Qué se guarda y cuánto, quién más ve su contenido, borrado a petición y lo que no se cobra |
| 14 | La API: primeros pasos | Etapa 2: entornos, el sobre, la clave de idempotencia y su primera llamada |
| 15 | Referencia de operaciones | Las ocho operaciones de /v1 campo por campo, con ejemplos ejecutables, y los nueve permisos de una clave |
| 16 | Errores de la API | Los treinta códigos, con la acción que le toca a cada uno |
| 17 | Trabajos y reintentos | Consulta de estado, retención del resultado y los cinco casos de una clave repetida |
| 18 | Ritmo y cuotas | Ritmo por credencial, cabeceras de saldo, concurrencia y cupo por entorno |
Requisitos previos
- Un servidor HTTPS alcanzable desde internet, con certificado válido.
- Un entorno de pruebas separado de producción (la certificación escribe en él).
- Revisión del protocolo: 2026-07-28 recomendada. Los SDK oficiales de TypeScript, Python, Go y
C# la implementan en su línea v2. Un servidor de la revisión anterior (saludo
initialize) también se admite y se certifica igual: se declara su era al dar de alta (página 09).
Convenciones de esta documentación
- DEBE: requisito. Su ausencia bloquea la certificación.
- DEBERÍA: recomendado. Genera aviso, no bloquea.
- PUEDE: opcional.
Los nombres de herramienta de los ejemplos son ilustrativos: usted nombra las suyas. Lo que está fijado es la forma, no los identificadores.
Para agentes de IA
Si va a implementar esto con un asistente de programación, no le pase la página HTML: pásele uno de estos enlaces. Devuelven Markdown plano, sin navegación ni maquetado.
- /llms-full.txtToda la documentación en un archivo Markdown. Es el enlace que conviene pasarle a un agente.
- /llms.txtÍndice compacto con un enlace por página, en el orden de implementación.
- /docs/01-quickstart.mdCualquier página en Markdown plano: la misma ruta con sufijo .md.