# 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](./11-webhooks.md)). 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](./09-changelog.md))— 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](./08-certification.md)). **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:

1. **Conectar.** Usted publica un **servidor MCP**
   ([Model Context Protocol](https://modelcontextprotocol.io), estándar abierto) y entrega a Asixto
   dos datos: **la URL y una credencial**.
2. **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](./04-capabilities.md)).
3. **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](./01-quickstart.md) | La primera hora: servidor mínimo funcionando y probado en local |
| 02 | [Contrato de herramientas](./02-tool-contract.md) | Referencia: entrada, salida, anotaciones, nombres |
| 03 | [Autenticación](./03-authentication.md) | OAuth 2.1, metadatos de recurso protegido, token rotable |
| 04 | [Catálogo requerido](./04-capabilities.md) | Qué exponer según lo que quiera que el agente resuelva |
| 05 | [Garantías obligatorias](./05-guarantees.md) | Idempotencia, propiedad, estado terminal, dato crítico |
| 06 | [Errores](./06-errors.md) | Forma del error y códigos que interpreta el agente |
| 07 | [Límites y rendimiento](./07-limits.md) | Latencia, tamaños, paginación, cuotas |
| 08 | [Certificación](./08-certification.md) | Comprobaciones automáticas antes de producción |
| 09 | [Versionado](./09-changelog.md) | Revisión del protocolo y política de cambios |
| 10 | [Operación y soporte](./10-operation.md) | Reintentos, concurrencia, caídas, pruebas con agente real, trazas y contacto |
| 11 | [Webhooks](./11-webhooks.md) | Etapa 2: firma, ventana anti-replay, deduplicación, catálogo de eventos y reintentos de entrega |
| 12 | [Precios](./12-pricing.md) | 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](./13-data.md) | 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](./14-api-quickstart.md) | **Etapa 2**: entornos, el sobre, la clave de idempotencia y su primera llamada |
| 15 | [Referencia de operaciones](./15-api-reference.md) | Las ocho operaciones de `/v1` campo por campo, con ejemplos ejecutables, y los nueve permisos de una clave |
| 16 | [Errores de la API](./16-api-errors.md) | Los treinta códigos, con la acción que le toca a cada uno |
| 17 | [Trabajos y reintentos](./17-jobs.md) | Consulta de estado, retención del resultado y los cinco casos de una clave repetida |
| 18 | [Ritmo y cuotas](./18-api-limits.md) | 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](./09-changelog.md)).

## 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.