Arquitectura y flujos de una integración
Los cuatro flujos que componen 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.
Actualizado el . 3 min de lectura
Incluido en todos los planes. Ver precios
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
Tu aplicación
Tu servidor llama
Con la cabeceraX-Api-Key.API externa
Controles
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.
UTILIA OS
La operación
Crea o lee tickets, usuarios, facturas, clientes, archivos...Métricas de la aplicación
Queda registrada
Con su ruta, su código de respuesta y su duración.
Las métricas se ven en la pestaña Métricas de la ficha de la aplicación. Detalle de los controles en Autenticación con clave de acceso.
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.
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
En cola
pending
El trabajo espera su turno.Se llega desde En cola cuando: Empieza el análisis
En proceso
processing
En tiempo real, llegan eventos progress.Se llega desde En proceso cuando: El análisis falla
Fallido
failed
Estado final
error explica el motivo.
Se llega desde En proceso cuando: Termina bien
Completado
completed
Estado final
result trae las sugerencias o la transcripción.
Detalle en Endpoints de sugerencias con IA y Endpoints de transcripción.
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.
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, desde tu servidor, con módulo, fichero, línea y contexto.POST /external/v1/tickets/client-errors, desde el navegador o el SDK, en lotes.
Los errores iguales se agrupan (la respuesta indica deduplicated: true cuando ya existía uno igual) y aparecen en la pestaña Errores de la ficha de la aplicación, desde donde el equipo puede resolverlos o vincularlos a un ticket o a una tarea. Detalle en Endpoints de errores de tu aplicación.
Siguiente paso
Si buscas cómo está construida la plataforma en conjunto, sigue con Arquitectura de la plataforma.