API de administración de integraciones

Esta página es la referencia de la API de administración de aplicaciones externas: los endpoints bajo /api/integrations/apps que crean, configuran y vigilan las aplicaciones externas de tu organización. Es la misma API que usa la pantalla Aplicaciones externas; el recorrido por esa pantalla está en Panel de aplicaciones externas.

Autenticación

Todos los endpoints exigen un token de sesión válido en la cabecera Authorization, con el prefijo Bearer: el mismo que emite el inicio de sesión en UTILIA OS. El plan de tu organización tiene que incluir el aplicativo Integraciones.

Authorization: Bearer <token_de_sesion>

Sin token, o con uno caducado, la respuesta es 401. Con un token válido pero sin el permiso, 403. Se usa la sesión y no una clave de aplicación porque esta API crea credenciales, regenera claves y concede permisos sensibles: es justo lo que gestiona.

Permisos

Cada endpoint exige uno de estos cuatro permisos de Integraciones:

EXTERNAL_APPS_VIEWpermiso

Ver aplicaciones externas. Necesario para todas las lecturas: listado, detalle, cifras, métricas, avisos y facturación.

EXTERNAL_APPS_CREATEpermiso

Crear aplicaciones externas. Necesario para POST /api/integrations/apps.

EXTERNAL_APPS_EDITpermiso

Editar aplicaciones externas. Necesario para actualizar, regenerar claves, configurar avisos, permisos, OAuth y facturación.

EXTERNAL_APPS_DELETEpermiso

Desactivar aplicaciones externas. Necesario para DELETE /api/integrations/apps/:id, que desactiva sin borrar información.

Endpoints

Todas las rutas comparten el prefijo global /api. El recurso base es /api/integrations/apps.

Gestión de apps

Ninguna lectura devuelve claves. Desde el 5 de septiembre de 2026, ni el listado ni el detalle traen la clave de firma de los avisos (ni cifrada): solo webhookSecretConfigured, que dice si hay una puesta. De la clave de API llegan el prefijo y los datos de uso, nunca su huella.

Permisos de la API

El catálogo, las reglas de concesión, el recorte por plan (400 SCOPE_OUT_OF_PLAN), el bloqueo optimista y la auditoría están en Permisos de la API.

Avisos a tu servidor

OAuth

Métricas

Todas aceptan el parámetro de consulta period (24h, 7d, 30d o 90d; por defecto, 24h), salvo /metrics/ai, que usa startDate y endDate. El detalle de las respuestas está en Métricas de la API.

/metrics/ai solo devuelve el consumo dentro de tu organización: si la aplicación no existe o es de otra organización, responde 404.

Tope de coste de IA de la app

Estos dos endpoints gobiernan el tope mensual de coste de IA de una aplicación externa: cuánto puede gastar y cuánto lleva gastado este mes. Sirven para acotar el gasto de los agentes de IA que la aplicación gestiona en los canales del chat, así que además del permiso exigen la capacidad de agentes de canal (chat.channel_agents) en el plan; sin ella, la respuesta es un bloqueo de plan (CAPABILITY_NOT_ENABLED), no un error de permisos.

Facturación y cobro por aplicación externa

Estos endpoints llevan, además del permiso, las puertas del plan del aplicativo al que pertenece cada dato. Sin el aplicativo contratado responden 403 con errorCode: 'MODULE_NOT_ENABLED', que no se resuelve concediendo permisos al usuario.

Los permisos de cada fila son una conjunción: hacen falta todos.

Desde el 5 de septiembre de 2026, :id/billing-config solo exige Integraciones y Finanzas, sin la pasarela: ese ajuste permite emitir facturas, que funciona sin Stripe (se factura por transferencia y el cobro se registra a mano). La pasarela gobierna los cobros: :id/payments*, :id/payment-authorizations* y los cobros con tarjeta. Sin ella, :id/billing-summary devuelve cardCharge y paymentAuthorization como out_of_plan, con el resto disponible.

Suscripciones y autorizaciones de cobro por aplicación

GET /api/integrations/apps/:id/users incluye siempre el clientId de cada usuario, y el bloque client con el nombre de la ficha solo si quien llama tiene CLIENTS_VIEW. No se devuelve clientId: null a quien no ve clientes, porque diría que el usuario no tiene ficha, y sería falso.

Origen de las facturas en Finanzas

El listado y el detalle de facturas de Finanzas devuelven además externalApp y externalUser cuando la factura viene de una aplicación externa, y aceptan el filtro externalAppId. Ambos bloques se recortan si quien llama no tiene EXTERNAL_APPS_VIEW.

Crear una aplicación externa

En el cuerpo de POST /api/integrations/apps solo name y slug son obligatorios.

Ejemplos

Los ejemplos usan la cabecera Authorization: Bearer <token>. Sustituye $TOKEN por tu token de sesión.

Listar aplicaciones externas

curl -X GET 'https://os.utilia.ai/api/integrations/apps?includeInactive=true' \
  -H 'Authorization: Bearer '"$TOKEN" \
  -H 'Content-Type: application/json'

Crear una aplicación externa

curl -X POST 'https://os.utilia.ai/api/integrations/apps' \
  -H 'Authorization: Bearer '"$TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Mi integración",
    "slug": "mi-integracion",
    "description": "Sincroniza tickets con nuestro CRM externo",
    "allowedOrigins": ["https://app.ejemplo.com"]
  }'

Regenerar la clave de API de una aplicación

curl -X POST 'https://os.utilia.ai/api/integrations/apps/APP_ID/regenerate-api-key' \
  -H 'Authorization: Bearer '"$TOKEN" \
  -H 'Content-Type: application/json'

Errores comunes

400 Bad Requesterror

Cuerpo no válido (por ejemplo, slug con caracteres no permitidos o tamaños fuera de rango).

401 Unauthorizederror

Falta el token de sesión en Authorization, ha caducado o no es válido.

403 Forbiddenerror

Falta el permiso EXTERNAL_APPS_* del endpoint, o el plan no incluye el aplicativo o la capacidad.

404 Not Founderror

La aplicación indicada en :id no existe en tu organización.

Siguiente paso

• Permisos de la APIConcede y retira permisos a una aplicación: catálogo, reglas y auditoría.
• Métricas de la APITráfico, latencia y errores de cada aplicación externa.
• Avisos a tu servidorConfigura, prueba y revisa la entrega de eventos a tu sistema.