Panel de aplicaciones externas
Cómo se crea y se configura una aplicación externa en UTILIA OS: claves, permisos de la API, avisos a tu servidor, usuarios externos, facturación y métricas, con los endpoints que usa el panel.
Actualizado el . 15 min de lectura
Incluido en todos los planes. Ver precios
Desde la pantalla Aplicaciones externas das de alta y gobiernas cada aplicación (propia o de terceros) que usa la API externa de UTILIA OS con una clave de API o un cliente OAuth: creas la aplicación, gestionas sus credenciales, le concedes permisos, configuras sus avisos a tu servidor, consultas sus usuarios externos y vigilas cómo usa la API.
Todo esto se apoya en la API de administración de integraciones
(/api/integrations/apps/...), que se llama con la sesión de un usuario
(Authorization: Bearer <token>) y se protege con los permisos
EXTERNAL_APPS_*. No la confundas con la API externa
(/api/external/v1/...), que es la que usa la propia aplicación con su
cabecera X-Api-Key y que documentan el resto de páginas de esta
sección.
Poner en marcha una aplicación externa
Aplicaciones externas
Crear la aplicación
La clave de API y la clave de firma de los avisos se muestran una sola vez.Ajustes › Permisos
Solo los que vaya a usar. Los protegidos los concede un Super Administrador.
Dónde está
En el menú de Gestión de proyectos, la entrada se llama
Aplicaciones externas, necesitas entrar con tu cuenta. Hoy esa
entrada solo aparece si tu organización usa el perfil de trabajo
«Software / Desarrollo» en Gestión de proyectos; con otro perfil la
pantalla queda oculta, aunque los permisos y la API siguen igual. Hace
falta además el aplicativo Integraciones en el plan y el permiso
EXTERNAL_APPS_VIEW.
Cada aplicación abre una ficha con doce secciones:
| Pestaña | Qué contiene |
|---|---|
| General | Ficha, cifras de uso y lista de comprobación para empezar. |
| Facturación | Interruptor de facturación, tope por factura, envío por correo, cuenta de cobro y fila de capacidades. |
| Facturas | Facturas emitidas por la aplicación, con su PDF y su enlace a Finanzas. |
| Cobros | Cobros procesados, con su estado y su origen. |
| Suscripciones | Cuotas recurrentes de los usuarios, con su próximo cobro y acciones de pausa y baja. |
| Autorizaciones de cobro | Autorizaciones firmadas y el bloque «Cobros que hoy no saldrían». |
| Usuarios | Usuarios finales de la aplicación y su ficha de cliente en el CRM. |
| Avisos a tu servidor | Dirección de entrega, eventos suscritos, clave de firma e historial de envíos. |
| Métricas | Tráfico, latencia y errores de la API. |
| Errores | Errores que ha enviado la aplicación (ver Pestaña de errores). |
| OAuth | Cliente OAuth de la aplicación, si lo tiene. |
| Ajustes | Pestañas General, Permisos (los permisos de la API), Chat, Widget y Avanzado (tamaño máximo de archivo y cuota de almacenamiento). |
Las cuatro secciones de facturación y cobro solo aparecen si la aplicación tiene concedido algún permiso de esa familia. Si el plan de tu organización no incluye el aplicativo o la capacidad, la sección no desaparece: se muestra con un candado que dice qué falta. A quien no tiene permiso para ver ese dato no se le ofrece la sección.
La pantalla de Facturación
Aquí se decide qué puede hacer la aplicación con el dinero.
- Activar la facturación: permite a la aplicación emitir facturas y cobrar. Solo puede encenderla un Super Administrador, y al guardar se le pide un motivo de al menos veinte caracteres que queda en el registro de auditoría. Apagarla no exige nada. La pantalla y su interruptor piden Integraciones y Finanzas, no la pasarela: una organización sin Stripe activa aquí la facturación igual, emite, envía y anota el cobro por transferencia. La pasarela solo gobierna los cobros con tarjeta.
- Tope por factura: importe máximo que la aplicación puede facturar de una vez. Por encima, la API responde con un error de límite.
- Enviar las facturas por correo al emitirlas: cuando está activo, UTILIA OS manda cada factura al usuario con la plantilla y el PDF de la organización. Cada llamada de la API puede saltárselo.
- Cuenta de cobro: los cobros se procesan con la cuenta Stripe de tu organización; no hay cuenta por aplicación. La pantalla muestra su estado y enlaza a Finanzas › Ajustes › Pagos con tarjeta (Stripe).
- Fila de capacidades: factura puntual, cobro con tarjeta, suscripción y autorización de cobro, cada una con su estado real. Cuando algo no se puede, distingue las dos razones, porque se arreglan en sitios distintos: no incluida en tu plan y permiso no concedido a la aplicación.
Autenticación y permisos
Todos los endpoints de la API de administración están bajo /api/integrations/apps y exigen una sesión válida (Bearer JWT), el aplicativo Integraciones en el plan y el permiso correspondiente. Los de facturación exigen además Finanzas, y los de cobros con tarjeta, también Pagos con tarjeta (Stripe).
- EXTERNAL_APPS_VIEWpermisoobligatorio
- Ver el listado, el detalle, las estadísticas, los usuarios, las métricas, las entregas de avisos, la facturación y el catálogo de permisos de la API.
- EXTERNAL_APPS_CREATEpermisoobligatorio
- Crear una aplicación externa nueva.
- EXTERNAL_APPS_EDITpermisoobligatorio
- Editar la aplicación, regenerar credenciales, cambiar sus permisos, configurar y probar avisos, gestionar OAuth y facturación, activarla o desactivarla.
- EXTERNAL_APPS_DELETEpermisoobligatorio
- Eliminar (desactivar) una aplicación externa.
Con EXTERNAL_APPS_EDIT cambias la mayoría de los permisos de la API,
pero los 14 protegidos (datos personales críticos, como las notas
internas de un contacto; críticos financieros, como cobrar o devolver
dinero; y la gestión de agentes de IA del chat) exigen además ser Super
Administrador y un motivo de al menos veinte caracteres, que queda en
el registro de auditoría. El catálogo llega marcado según el plan:
solo se pueden conceder los permisos que cubre tu plan, y conceder uno
fuera de plan responde 400 SCOPE_OUT_OF_PLAN. Lo ya concedido no se
borra al bajar de plan; simplemente deja de funcionar.
Listado de aplicaciones
La página principal lista las aplicaciones externas de tu organización.
/api/integrations/appsLista las aplicaciones externas. Por defecto solo las activas; con includeInactive=true, también las desactivadas. Permiso: EXTERNAL_APPS_VIEW.
- includeInactivequery (boolean)
- Si es 'true', incluye también las aplicaciones desactivadas. Por defecto solo se devuelven las activas (isActive=true).
Cada elemento trae los recuentos de tickets y de usuarios externos (_count), el proyecto de Gestión de proyectos vinculado (devProject, si lo hay) y oauthEnabled, que indica si la aplicación tiene un cliente OAuth activo.
Crear una aplicación externa
El alta crea en una sola operación la aplicación, su clave de API y la clave de firma de sus avisos.
/api/integrations/appsCrea una aplicación externa con su clave de API y la clave de firma de sus avisos. Permiso: EXTERNAL_APPS_CREATE.
Define la identidad de la aplicación
nameyslugson obligatorios. Elslugsolo admite minúsculas, números y guiones (^[a-z0-9-]+$) y tiene que ser único en tu organización. Si quieres, añadedescription,logoUrlywebsiteUrl.Ajusta la conversación en los dos sentidos y la IA
Campos opcionales con valores por defecto:
allowBidirectional(por defectotrue),showAgentNames(por defectofalse),customAgentName,aiTranscriptionEnabled(por defectotrue) yaiSuggestionsEnabled(por defectotrue).Configura orígenes y límites de archivos
allowedOriginses la lista de orígenes CORS permitidos.maxFileSize(entre 1 KB y 100 MB) ymaxStorageBytes(entre 1 MB y 10 GB) limitan la subida de archivos. CondevProjectIdvinculas la aplicación a un proyecto de Gestión de proyectos.Guarda la clave de API y la clave de firma
La respuesta devuelve
apiKeyPlainTextywebhookSecretPlainText. Es la única vez que viajan en claro: cópialas y guárdalas en un sitio seguro. Después solo se mostrará el prefijo de la clave.
- namestring (máx. 100)obligatorio
- Nombre visible de la aplicación.
- slugstring (máx. 50)obligatorio
- Identificador único en tu organización. Solo minúsculas, números y guiones.
- descriptionstring
- Descripción de la aplicación.
- logoUrlurl
- URL del logotipo.
- websiteUrlurl
- URL del sitio web de la aplicación.
- allowBidirectionalboolean
- Permite la conversación en los dos sentidos. Por defecto true.
- showAgentNamesboolean
- Muestra los nombres reales de las personas de soporte. Por defecto false.
- customAgentNamestring (máx. 100)
- Nombre genérico que se muestra cuando no se enseñan los reales.
- aiTranscriptionEnabledboolean
- Habilita la transcripción por IA. Por defecto true.
- aiSuggestionsEnabledboolean
- Habilita las sugerencias por IA. Por defecto true.
- allowedOriginsstring[]
- Orígenes CORS permitidos. No se admite el comodín '*' suelto.
- devProjectIdstring | null
- Proyecto de Gestión de proyectos al que se vincula la app.
- maxFileSizeint (bytes)
- Tamaño máximo por archivo. Entre 1024 (1 KB) y 104857600 (100 MB).
- maxStorageBytesint (bytes)
- Almacenamiento total máximo. Entre 1048576 (1 MB) y 10737418240 (10 GB).
El servidor rechaza * como valor de allowedOrigins. Se admiten comodines de subdominio (por ejemplo, https://*.cliente.com), pero nunca el comodín suelto, que abriría la aplicación a peticiones desde cualquier origen.
Detalle y estadísticas
/api/integrations/apps/:idDetalle de la aplicación, con su clave de API (solo prefijo y datos de uso), el proyecto vinculado y el cliente OAuth si existe. Permiso: EXTERNAL_APPS_VIEW.
/api/integrations/apps/:id/statsEstadísticas de la aplicación: tickets totales, abiertos y resueltos, usuarios externos, desglose por categoría y prioridad, actividad reciente y resumen de errores. Permiso: EXTERNAL_APPS_VIEW.
Ninguna lectura devuelve credenciales. De la clave de API llegan el keyPrefix, el rateLimit, el usageCount, la fecha de último uso y si está activa, nunca su huella. De la clave de firma de los avisos llega solo webhookSecretConfigured, un booleano que dice si hay clave puesta: ni el valor en claro ni su versión cifrada viajan en el listado ni en el detalle. Para volver a tener una credencial completa hay que regenerarla.
Configuración de la aplicación
La sección Ajustes cubre la edición general, la regeneración de credenciales y la activación o desactivación.
/api/integrations/apps/:idActualiza la aplicación. Acepta los mismos campos que el alta, todos opcionales. Permiso: EXTERNAL_APPS_EDIT.
/api/integrations/apps/:id/regenerate-api-keyGenera una clave de API nueva en el mismo registro y la devuelve en claro una sola vez. Permiso: EXTERNAL_APPS_EDIT.
/api/integrations/apps/:id/regenerate-webhook-secretGenera una clave de firma de avisos nueva, anula la anterior y la devuelve en claro una sola vez. Permiso: EXTERNAL_APPS_EDIT.
/api/integrations/apps/:id/toggle-activeActiva o desactiva la aplicación (isActive). Permiso: EXTERNAL_APPS_EDIT.
/api/integrations/apps/:idElimina la aplicación de forma lógica: la marca como inactiva (isActive = false) sin borrar el registro. Permiso: EXTERNAL_APPS_DELETE.
Eliminar es desactivar: la aplicación y su historial se conservan. Deja
de salir en el listado por defecto, pero se puede consultar con
includeInactive=true y reactivar con toggle-active.
Regenerar credenciales rompe las activas
Al regenerar la clave de API o la clave de firma de los avisos, la anterior deja de funcionar al momento. La aplicación que la usaba recibirá 401 (clave de API) o fallará al comprobar la firma (avisos) hasta que actualice la nueva en su lado.
Permisos de la API
Los permisos de la API (scopes) deciden qué puede leer y hacer la aplicación con la API externa. La pestaña Permisos se pinta con el catálogo que sirve el servidor, así que los textos, los distintivos y la exigencia de Super Administrador siempre coinciden con lo que el servidor aplica.
/api/integrations/apps/scopes/catalogCatálogo de permisos de la API, con los que no cubre el plan marcados como outOfPlan, y con etiqueta, descripción, tipo y marcas de protección. Permiso: EXTERNAL_APPS_VIEW.
/api/integrations/apps/:id/scopesSustituye la lista completa de permisos de la aplicación. El servidor calcula qué cambia y lo deja en el registro de auditoría. Permiso: EXTERNAL_APPS_EDIT.
Cada entrada del catálogo incluye:
- valuestringobligatorio
- Nombre técnico del permiso (por ejemplo, 'crm:contacts:read').
- labelstringobligatorio
- Etiqueta corta para la interfaz.
- descriptionstringobligatorio
- Explicación del permiso.
- category'basic' | 'write' | 'sensitive' | 'rgpd-critical' | 'financial-critical'obligatorio
- Tipo del permiso.
- rgpdSensitivebooleanobligatorio
- Si da acceso a datos personales en sentido amplio.
- rgpdCriticalbooleanobligatorio
- Si es un dato personal crítico.
- requiresSuperAdminbooleanobligatorio
- Si concederlo exige ser Super Administrador y dar un motivo.
- requiredModules / requiredCapabilitiesstring[]obligatorio
- Aplicativos y capacidades del plan que necesita para funcionar.
- outOfPlanboolean
- Si tu plan no lo cubre.
Sobre la actualización (PATCH .../scopes):
scopeslleva la lista completa que debe quedar, no solo los cambios. El servidor calculaaddedyremoved.reason(texto, hasta 500 caracteres) es obligatorio, con al menos 20, cuando se añade un permiso protegido.expectedUpdatedAt(ISO 8601) activa el bloqueo optimista: si la aplicación cambió después, la respuesta es409.- Retirar un permiso revoca los tokens OAuth activos que lo incluían. La clave de firma no se rota.
Respuestas de error específicas de este endpoint:
- 400 INVALID_SCOPEerror
- La lista scopes contiene un valor que no está en el catálogo.
- 403 SUPER_ADMIN_REQUIRED_FOR_RGPD_SCOPEerror
- Hace falta ser Super Administrador para añadir un permiso protegido.
- 400 SCOPE_OUT_OF_PLANerror
- El plan de tu organización no cubre ese permiso.
- 404 EXTERNAL_APP_NOT_FOUNDerror
- La aplicación no existe en tu organización.
- 409 EXTERNAL_APP_SCOPES_CONFLICTerror
- Bloqueo optimista: expectedUpdatedAt no coincide. También 409 EXTERNAL_APP_REVOKED si la aplicación está desactivada.
- 422 REASON_REQUIRED_FOR_RGPD_SCOPEerror
- Falta el motivo (mínimo 20 caracteres) al añadir un permiso protegido.
El catálogo completo por áreas y sus reglas están en Permisos de la API.
Avisos a tu servidor
Cada aplicación puede recibir avisos (webhooks) cuando pasa algo en UTILIA OS. Desde el panel configuras la dirección de destino y los eventos, pruebas la entrega y consultas el historial.
/api/integrations/apps/:id/webhookConfigura los avisos: dirección de destino, activación y eventos suscritos. Permiso: EXTERNAL_APPS_EDIT.
- webhookUrlurl | null
- Dirección HTTPS de destino. null para borrarla.
- webhookEnabledbooleanobligatorio
- Activa o desactiva la entrega de avisos.
- webhookEventsstring[]obligatorio
- Eventos a los que se suscribe la aplicación. Solo recibe los que declare aquí.
/api/integrations/apps/:id/webhook/testEnvía un aviso de prueba a la dirección configurada, después de comprobar que no apunta a una red privada. Permiso: EXTERNAL_APPS_EDIT.
La prueba responde 400 WEBHOOK_NO_URL si la aplicación no tiene dirección configurada, y 400 WEBHOOK_URL_INVALID si la dirección es una IP privada o se resuelve a una red privada (protección frente a SSRF y DNS rebinding). Si tu servidor responde con un código de error, cuenta como intento válido y el código se devuelve en el resultado.
Historial de entregas
/api/integrations/apps/:id/webhook-deliveriesHistorial paginado de entregas de avisos, con filtro por estado y por evento. Permiso: EXTERNAL_APPS_VIEW.
/api/integrations/apps/:id/webhook-deliveries/:deliveryIdDetalle de una entrega, con el contenido enviado y la respuesta de tu servidor. Permiso: EXTERNAL_APPS_VIEW.
/api/integrations/apps/:id/webhook-deliveries/:deliveryId/retryReintenta una entrega a mano. Responde 204 No Content. Permiso: EXTERNAL_APPS_EDIT.
Filtros admitidos en el listado:
- statusWebhookDeliveryStatus
- Filtra por estado de la entrega.
- eventstring
- Filtra por nombre de evento.
- pageint (≥1)
- Página. Por defecto 1.
- limitint (1-100)
- Tamaño de página. Por defecto 20.
El detalle de cada entrega trae event, status, statusCode, errorMessage, attemptCount, payload (el JSON enviado), responseBody, lastAttemptAt, nextRetryAt y completedAt.
Hay eventos de tickets, usuarios, archivos, errores, presupuestos, facturas, métodos de pago, autorizaciones de cobro, suscripciones, cobros, contactos, leads, clientes y chat. Cada uno tiene su descripción, su versión de contenido y su forma de envío (a todas las aplicaciones suscritas o solo a la implicada). El catálogo completo está en Avisos a tu servidor.
Usuarios externos
Lista los usuarios finales que la aplicación ha identificado.
/api/integrations/apps/:id/usersLista paginada de usuarios externos de la aplicación. Permiso: EXTERNAL_APPS_VIEW.
- pagequery (int)
- Página. Por defecto 1.
- limitquery (int)
- Tamaño de página. Por defecto 20.
Para unir un usuario de la aplicación con una ficha de cliente que ya
existía en el CRM (por ejemplo, creada por tu equipo), el panel usa
POST /api/integrations/apps/:id/users/:userId/link-client. Exige los
permisos EXTERNAL_APPS_EDIT y CLIENTS_VIEW, el CRM en el plan y
acceso a esa ficha; es la única forma de enlazar con una ficha nativa,
que la API externa nunca toca (ver Usuarios externos).
Métricas de la API
La sección Métricas resume cómo usa la aplicación la API externa. Todas las métricas admiten period con los valores 24h, 7d, 30d o 90d (por defecto, 24h).
/api/integrations/apps/:id/metricsResumen: total de peticiones, tiempo de respuesta medio, tasa de error, veces que se alcanzó el límite y variación frente al periodo anterior.
/api/integrations/apps/:id/metrics/requestsPeticiones a lo largo del periodo.
/api/integrations/apps/:id/metrics/latencyLatencia a lo largo del periodo: p50, p95, p99 y media.
/api/integrations/apps/:id/metrics/errorsErrores por código de estado HTTP y tipo de error.
/api/integrations/apps/:id/metrics/endpointsEndpoints más usados, con latencia media y tasa de error.
/api/integrations/apps/:id/metrics/webhooksEntregas de avisos correctas y fallidas, con desglose por evento.
El resumen (/metrics) devuelve:
- totalRequestsnumberobligatorio
- Total de peticiones en el periodo.
- avgResponseTimeMsnumberobligatorio
- Tiempo de respuesta medio en milisegundos.
- errorRatenumberobligatorio
- Tasa de error en porcentaje.
- rateLimitHitsnumberobligatorio
- Veces que se alcanzó el límite de peticiones.
- trendsobjectobligatorio
- Variación de requests, responseTime, errorRate y rateLimitHits frente al periodo anterior.
- periodstringobligatorio
- Periodo consultado.
El detalle de cada serie está en Métricas de la API.
OAuth
Además de la clave de API, una aplicación puede tener un cliente OAuth 2.0 para actuar en nombre de una persona que la autoriza.
/api/integrations/apps/:id/enable-oauthActiva OAuth para la aplicación. Exige al menos una redirect_uri. Permiso: EXTERNAL_APPS_EDIT.
/api/integrations/apps/:id/oauthActualiza la configuración OAuth de la aplicación. Permiso: EXTERNAL_APPS_EDIT.
/api/integrations/apps/:id/oauthDatos del cliente OAuth de la aplicación. Permiso: EXTERNAL_APPS_VIEW.
/api/integrations/apps/:id/disable-oauthDesactiva OAuth en la aplicación. Permiso: EXTERNAL_APPS_EDIT.
Parámetros principales al habilitar OAuth:
- redirect_urisurl[]obligatorio
- Direcciones de redirección autorizadas del cliente OAuth.
- allowed_scopesstring
- Scopes que puede pedir el cliente OAuth.
- token_endpoint_auth_method'none' | 'client_secret_basic' | 'client_secret_post'
- Método de autenticación en el endpoint de token.
- tos_uriurl
- Dirección de las condiciones del servicio.
- policy_uriurl
- Dirección de la política de privacidad.
- contact_emailemail
- Correo de contacto del cliente OAuth.
Las marcas is_first_party (aplicación propia, que se salta la pantalla
de consentimiento) y verified (insignia de aplicación verificada en esa
pantalla) solo puede ponerlas UTILIA OS. Si las envías a true, la
respuesta es 403 con errorCode: "SAAS_ADMIN_REQUIRED_FOR_OAUTH_TRUST";
a false se ignoran y no cambian nada.
El flujo de autorización, el intercambio de tokens y la pantalla de consentimiento están en Iniciar sesión con UTILIA.
Facturación de la aplicación
Si la aplicación emite facturas o cobra por la API, el panel permite consultarlo y configurarlo. Estos endpoints exigen además Finanzas en el plan, y los de cobros, también Pagos con tarjeta (Stripe).
/api/integrations/apps/:id/invoicesFacturas emitidas por la aplicación (origen EXTERNAL_APP), con filtros por usuario externo, estado y fechas. Permisos: EXTERNAL_APPS_VIEW e INVOICES_VIEW.
/api/integrations/apps/:id/invoices/statsTotales de las facturas emitidas por la aplicación. Permisos: EXTERNAL_APPS_VIEW e INVOICES_VIEW.
/api/integrations/apps/:id/paymentsCobros (PaymentIntents) procesados por la aplicación sobre sus facturas. Permisos: EXTERNAL_APPS_VIEW y PAYMENTS_VIEW.
/api/integrations/apps/:id/payments/statsTotales de los cobros procesados por la aplicación. Permisos: EXTERNAL_APPS_VIEW y PAYMENTS_VIEW.
/api/integrations/apps/:id/billing-configConfiguración de facturación de la aplicación. Permiso: EXTERNAL_APPS_VIEW.
/api/integrations/apps/:id/billing-configActiva o desactiva la facturación por API, fija el tope por factura en céntimos y decide si se envían por correo al emitirlas. Activarla exige ser Super Administrador y un motivo. Permiso: EXTERNAL_APPS_EDIT.
El recorrido completo, de la primera factura al cobro recurrente, está en Facturar y cobrar desde tu aplicación. Los endpoints de suscripciones, autorizaciones de cobro y resumen de facturación del panel están en la API de administración de integraciones.
Errores frecuentes
- 401error
- Falta la sesión o no es válida (Bearer JWT).
- 403error
- Falta el permiso EXTERNAL_APPS_*, hace falta ser Super Administrador para un permiso protegido o el plan no incluye el aplicativo.
- 404error
- La aplicación no existe en tu organización.
- 409error
- Slug repetido al crear, conflicto de bloqueo optimista en los permisos o aplicación desactivada.
Todo cambio sensible (permisos, credenciales, facturación) queda en el registro de auditoría. Las métricas y el historial de entregas son el primer sitio donde mirar ante latencia, errores o avisos que no llegan.