# Arquitectura y flujos de una integración

Los cuatro flujos de una integración con UTILIA OS: tu aplicación llama, UTILIA OS te avisa, la IA trabaja en segundo plano y una persona autoriza con OAuth.

Una integración con UTILIA OS se construye con cuatro flujos que se combinan. Esta página explica qué hace cada uno y dónde se documenta, para que elijas las piezas antes de escribir código.

## 1. Tu aplicación llama a la API

Es el flujo principal: tu servidor llama a `https://os.utilia.ai/api/external/v1/...` y cada petición recorre este camino.

**Una petición a la API externa**

1. **Tu servidor llama** (Tu aplicación): Con la cabecera `X-Api-Key`.
2. **Controles** (API externa): Clave, límite de uso, plan de la organización y permiso de la aplicación. Si no: 401, 403 o 429, con su errorCode.
3. **La operación** (UTILIA OS): Crea o lee tickets, usuarios, facturas, clientes, archivos...
4. **Queda registrada** (Métricas de la aplicación): Con su ruta, su código de respuesta y su duración.

Las métricas se ven en **Actividad › Métricas**, en la ficha de la aplicación. Detalle de los controles en [Autenticación con clave de acceso](https://os.utilia.ai/docs/developers/getting-started/authentication).

## 2. UTILIA OS avisa a tu servidor

Cuando algo cambia (un ticket recibe respuesta, se cobra una factura, un lead se cualifica), UTILIA OS envía un aviso firmado a la dirección que hayas configurado. Los avisos salen de una cola con reintentos y cada entrega lleva un identificador estable para que puedas descartar duplicados.

Detalle en [Avisos a tu servidor: visión general](https://os.utilia.ai/docs/developers/webhooks/overview).

## 3. La IA trabaja en segundo plano

Las sugerencias de IA para tickets y las transcripciones de audio no se resuelven en la misma petición: la API devuelve un `jobId` y el trabajo se encola. Recoges el resultado de una de dos maneras: en **tiempo real**, con `GET .../{jobId}/stream`, que emite los eventos `progress`, `completed` o `failed`; o **consultando** `GET .../{jobId}` cada pocos segundos hasta que el estado sea final.

**Estados de un trabajo de IA**

1. **En cola** (`pending`). El trabajo espera su turno.
2. **En proceso** (`processing`). Se llega desde En cola cuando: Empieza el análisis. En tiempo real, llegan eventos progress.
   - **Fallido** (`failed`, estado final). Se llega desde En proceso cuando: El análisis falla. error explica el motivo.
3. **Completado** (`completed`, estado final). Se llega desde En proceso cuando: Termina bien. result trae las sugerencias o la transcripción.

Detalle en [Endpoints de sugerencias con IA](https://os.utilia.ai/docs/developers/api/ticket-ai-suggestions) y [Endpoints de transcripción](https://os.utilia.ai/docs/developers/api/ticket-transcription).

## 4. Una persona autoriza con OAuth

Cuando tu aplicación tiene que actuar **en nombre de una persona** y con sus permisos (por ejemplo, un asistente que lee su agenda), la clave de API no sirve: se usa OAuth. El flujo separa cinco pasos, cada uno con su dirección:

| Paso | Dirección |
| - | - |
| Descubrimiento | `GET /.well-known/oauth-authorization-server` |
| Autorización de la persona | `GET /api/oauth/authorize` |
| Obtención del token | `POST /api/oauth/token` |
| Revocación | `POST /api/oauth/revoke` |
| Introspección | `POST /api/oauth/introspect` |

Detalle en [OAuth: visión general](https://os.utilia.ai/docs/developers/oauth/overview).

## Los errores de tu aplicación, en UTILIA OS

Tu aplicación también puede enviar sus propios errores a UTILIA OS para verlos junto al resto de la integración:

- `POST /external/v1/errors/report` y `/batch`, con módulo, fichero, línea y contexto, uno a uno o en lotes de 25. Es lo que usan `install` y `capture` del SDK, en el navegador y en tu servidor.
- `POST /external/v1/tickets/client-errors`, la telemetría ligera con la que el widget avisa de sus propios fallos.

Los errores iguales se agrupan (la respuesta dice si el grupo es nuevo, si ya existía o si estaba resuelto y se ha reabierto) y aparecen en **Actividad › Errores**, en la ficha de la aplicación, desde donde el equipo puede resolverlos, silenciarlos o vincularlos a un ticket o a una tarea. Detalle en [Capturar los errores de tu aplicación](https://os.utilia.ai/docs/developers/sdk/error-reporting).

## Siguiente paso

Si buscas cómo está construida la plataforma en conjunto, sigue con [Arquitectura de la plataforma](https://os.utilia.ai/docs/developers/getting-started/platform-architecture).