Panel de aplicaciones externas

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

1. Aplicaciones externas

   Crear la aplicación

   La clave de API y la clave de firma de los avisos se muestran una sola vez.

2. Configuración › Ajustes

   Conceder permisos

   Solo los que vaya a usar. Los protegidos los concede un Super Administrador.

3. Configuración · Opcional

   Configurar los avisos

   Dirección HTTPS y eventos suscritos, solo si tu servidor necesita enterarse al momento.

4. Dinero › Facturación · Opcional

   Activar la facturación

   Solo si la aplicación va a facturar o cobrar.

5. Pruebas · Opcional

   Probar la integración

   Diagnóstico, prueba de lectura, avisos de ejemplo y facturas sin emitir.

6. Tu servidor

   Llamar a la API

   Con la cabecera X-Api-Key.

Dónde está

La lista de aplicaciones está en Ajustes, Creadas por tu empresa, para cualquier organización, sea cual sea su perfil de trabajo.

Hace falta el aplicativo Integraciones en el plan y el permiso «Ver aplicaciones externas». Cada tarjeta enseña la salud de la aplicación en una línea y abre su ficha.

La ficha de una aplicación

La ficha agrupa sus pantallas en seis pestañas. Las que tienen varias pantallas enseñan debajo una segunda fila, más discreta, con cada una; en el teléfono, las dos filas se desplazan de lado a lado. Las direcciones no cambian: un enlace guardado a /integrations/:id/webhooks sigue abriendo Avisos a tu servidor, ahora dentro de Configuración.

Aplicaciones externas · ResumenEjemplo

Resumen

2

ResumenPruebasActividadDineroUsuariosConfiguración1

3

1. 1
   Seis pestañas. La que tiene más de una pantalla abre debajo una segunda fila con ellas.
2. 2
   Estado: el veredicto de la integración en una línea, con el enlace a Pruebas.
3. 3
   Información y clave de API: persona responsable, prefijo de la clave, cupo por hora y último uso.

En Dinero, Facturación está siempre; las otras cuatro pantallas solo aparecen si la aplicación factura de verdad. Si el plan de tu organización no incluye el aplicativo o la capacidad de una pantalla, 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 pantalla, y una pestaña sin ninguna pantalla visible no sale. Pruebas, la segunda pestaña, está siempre a la vista: es lo que se usa antes de que la aplicación funcione y lo primero que se abre cuando deja de funcionar.

El estado de la aplicación

El bloque Estado del Resumen es una sola línea: el veredicto de la integración en una palabra (Funciona, Funciona en parte, Revisar, No funciona, Sin uso, Desactivada o Sin comprobar), la frase del servidor con el porqué y un enlace a Pruebas, que lo cuenta entero con la acción de cada cosa. Es el mismo diagnóstico que pinta Pruebas, que lee la aplicación con su clave en GET /external/v1/diagnostics y que resume el MCP, así que las pantallas no se contradicen. Si la comprobación no llega, la línea lo dice con Reintentar: nunca lo presenta como un fallo de la integración.

La pestaña Pruebas

Dice si la integración funciona y, si no, por qué y quién lo arregla, sin emitir nada real. Todo sale del diagnóstico del servidor: la pestaña no calcula nada por su cuenta. Las pruebas las ejecuta el servidor en nombre de la aplicación, con su plan y sus permisos de la API, así que el panel nunca te pide la clave ni la guarda. Cómo se prueba una integración paso a paso está en Probar tu integración, y cada hallazgo, en Hallazgos del diagnóstico.

Aplicaciones externas · PruebasEjemplo

Pruebas

3

2

1

4

6

5

1. 1
   Pruebas es la segunda pestaña de la ficha, justo después de Resumen.
2. 2
   Instrucciones para tu asistente de IA: el texto para el asistente de quien programa, sin la clave.
3. 3
   El estado: el veredicto en una palabra, desde cuándo, una sola acción y el pulso de las últimas 24 horas.
4. 4
   Diagnóstico: un área por fila, lo que falla arriba, con quién lo arregla y su acción en la misma fila.
5. 5
   Recorrido: los primeros pasos de la integración, marcados solos con lo que observa el servidor.
6. 6
   En directo: las llamadas de la aplicación según llegan, sin recargar la página.

El estado y el pulso

Arriba, el veredicto en una palabra, la frase del servidor con el porqué, desde cuándo y, si hace falta, una sola acción: un enlace que lleva al sitio exacto y te devuelve a esta pestaña, o un diálogo en el sitio (nombrar a la persona responsable, renovar la clave). Si no puedes hacerla, en su lugar va la frase de quién puede. Al lado, el pulso de las últimas 24 horas: una barra por hora, con lo rechazado en color. Mientras la aplicación no ha llamado nunca, en el sitio del pulso aparece Haz tu primera llamada, con el fragmento mínimo para hacerla con la clave en UTILIA_API_KEY.

Diagnóstico y recorrido

Diagnóstico es una lista con un área por fila: aplicación, persona responsable, clave de API, permisos de la API, facturación (si la aplicación factura), avisos a tu servidor (si los tiene) y llamadas. Lo que falla sube; cada fila dice quién lo arregla, sin culpar a nadie, y lleva su acción. Conceder un permiso solo se ofrece a quien puede concederlo; ante llamadas rechazadas por falta de permiso, la acción es Revisar el permiso, porque unas llamadas rechazadas no prueban que la integración lo necesite.

Recorrido lista los primeros pasos según para qué sirve la aplicación y los marca solo, con la fecha de su evidencia: el progreso es el mismo para todo el equipo y en cualquier aparato. Cada paso pendiente dice cómo se hace y enlaza a la guía. Probar aquí solo aparece en el paso del receptor de avisos, el único que una prueba del panel puede marcar: la factura de prueba y la prueba activa no pasan por la clave de la aplicación.

Lanzar una prueba

Un selector con las pruebas que tienen sentido para esta aplicación y para ti, y debajo, el panel de la elegida:

• Comprobar ahora: una lectura mínima con cada permiso de lectura, como lo haría la aplicación, sin escribir nada ni devolver datos. Si la aplicación factura, valida además una factura de ejemplo sin emitirla; ese bloque solo lo ve quien puede ver facturas. Hasta 6 por minuto y persona, sin gastar el cupo de la clave.
• Comprobar una petición: pegas el método, la ruta y el cuerpo que manda tu programa y el servidor dice, sin ejecutarla, si pasaría y por qué no, con los campos que se descartarían resaltados. La ruta se autocompleta con lo que la aplicación puede llamar. El cuerpo no se guarda.
• Aviso de prueba: envía a la dirección guardada una muestra del evento que elijas, firmada igual que los avisos reales y marcada como prueba (livemode: false y meta.test: true).
• Receptor de avisos: tres avisos de prueba que tu servidor tiene que aceptar, el bueno, y rechazar, el de firma falsa y el caducado. El resultado queda guardado para el diagnóstico y el recorrido.
• Factura sin emitir: el editor de una factura de ejemplo con Probar aquí, que la valida sin reservar número, y el PDF de muestra sin validez fiscal. Si el correo saldría al contacto de facturación del cliente del CRM, solo lo ve entero quien puede ver todos los clientes; si no, enmascarado. El borrador se guarda en esa pestaña del navegador mientras dura la sesión, sin datos personales.

La prueba abierta queda en la dirección de la página, así que un enlace pegado en el chat abre la misma prueba, y al volver de arreglar algo aterrizas en ella. Con teclado, el atajo (Cmd + Intro en Mac, Ctrl + Intro en Windows y Linux) lanza la prueba abierta desde cualquier campo de su panel.

En directo y qué puede llamar

En directo enseña las últimas 50 llamadas de la aplicación según llegan, sin sondear: método, ruta, estado, tiempo, si usó la clave anterior y, si falla, qué significa. Filtra entre Todas y Rechazadas, y Pausar deja la lista quieta. Una llamada que el programa cortó antes de recibir la respuesta sale con el estado 499. En el ordenador, desde una llamada, Comprobar esta ruta abre Comprobar una petición ya rellena.

Qué puede llamar agrupa las rutas de la API por recurso, con cuántas puede llamar la aplicación hoy. Al desplegar cada grupo, la ruta que no se puede llamar dice por qué: el permiso que falta, con Conceder si puedes concederlo; un aplicativo o una función que el plan no incluye, con su candado; o «Próximamente», sin venta. En el ordenador, cada ruta lleva además Comprobar esta ruta. Lo que la aplicación no tiene concedido no es un problema: va al final, plegado.

Quién puede hacer cada cosa

Todo exige el aplicativo Integraciones en el plan, también a un Super Administrador. Lo que no puedes hacer no aparece: sin permiso para enviar avisos no ves esas dos pruebas, y una aplicación que no factura no enseña nada de facturación. Cada pieza llama a su ruta del panel, bajo /api/integrations/apps/:id:

Los dos avisos de prueba exigen además el aplicativo del evento y comparten con la clave de la aplicación un cupo de 5 por minuto. Una aplicación de otra organización, o eliminada, responde 404 APP_NOT_FOUND, igual que una que no existe.

En directo no sondea: escucha GET /diagnosis/stream, un canal en tiempo real que solo avisa de que hay llamadas nuevas o de que cambió la salud, sin datos, y el panel vuelve a pedir lo que necesita. Se abre con un pase de corta duración (POST /auth/sse-token) en ?token=, admite 5 conexiones a la vez por persona y el servidor lo cierra a los 15 minutos; el panel vuelve a conectarse solo, pasando otra vez por tu sesión, tu permiso y el plan. Además, cada 5 minutos comprueba que sigues teniendo EXTERNAL_APPS_VIEW, que la organización sigue teniendo Integraciones y que la aplicación existe; si algo falla, lo cierra.

En el teléfono y en el escritorio

• Teléfono, en la aplicación móvil o en el navegador: las pruebas son una lista y cada una se abre en una hoja inferior. Lo que necesita un editor, Comprobar una petición y Factura sin emitir, no se programa en el teléfono: se ofrece Enviar al ordenador, que abre la hoja de compartir del sistema con el enlace a esa misma prueba. Instrucciones para tu asistente de IA también se comparte en lugar de copiarse, y el detalle de una llamada de En directo se abre en una hoja inferior.
• Aplicación de escritorio: mientras En directo escucha y la ventana está en segundo plano, una notificación del sistema te avisa de la primera llamada de la aplicación y de cada fallo nuevo, otra ruta u otro código en esa sesión. Respeta tu ajuste de notificaciones de escritorio y se apaga con Pausar. El PDF de muestra se descarga con su aviso nativo y Mostrar en la carpeta.

Cuando una aplicación deja de funcionar (su salud pasa a No funciona), el aviso que recibes en la aplicación y por correo lleva a esta pestaña. Cada persona decide por dónde le llega en Mi perfil, Avisos, fila Integraciones, bloque Salud de las aplicaciones, aviso Una aplicación deja de funcionar. Qué hace cambiar la salud está en Salud de la aplicació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. Es lo que decide cuando la llamada no dice nada: sendEmail manda sobre él en los dos sentidos (true la envía aunque esté apagado y false la retiene aunque esté encendido). El justificante de cobro y los avisos de vencimiento y recordatorio dependen solo de este interruptor.
• 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, el catálogo de permisos de la API y el diagnóstico, y lanzar las pruebas de solo lectura de la pestaña Pruebas.

EXTERNAL_APPS_CREATEpermisoobligatorio

Crear una aplicación externa nueva.

EXTERNAL_APPS_EDITpermisoobligatorio

Editar la aplicación, renovar sus claves de API y de firma, cambiar sus permisos, configurar y probar avisos, gestionar OAuth y facturación, activarla o desactivarla.

EXTERNAL_APPS_DELETEpermisoobligatorio

Eliminar una aplicación externa (se puede restaurar), ver las eliminadas y restaurarlas, y eliminarla definitivamente.

Con EXTERNAL_APPS_EDIT cambias la mayoría de los permisos de la API, pero los 17 protegidos (datos personales críticos, como las notas internas de un contacto o el NIF de los usuarios; críticos financieros, como cobrar, programar cobros, devolver dinero o emitir rectificativas; 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.

includeInactivequery (boolean)

Si es 'true', incluye también las aplicaciones desactivadas que no están eliminadas. Por defecto solo se devuelven las activas.

deletedquery ('exclude' | 'only')

'exclude', el valor por defecto, deja fuera las eliminadas. 'only' devuelve solo las eliminadas, la vista «Eliminadas» del panel. Cualquier otro valor responde 400 VALIDATION_ERROR.

Cada elemento trae los recuentos de tickets y de usuarios externos (_count), el proyecto de Gestión de proyectos vinculado (devProject, si lo hay), oauthEnabled, que indica si la aplicación tiene un cliente OAuth activo, y deletedAt, la fecha en que se eliminó o null. En la vista de eliminadas llega también quién la eliminó (deletedBy).

Trae además la salud de cada aplicación, la misma línea que pinta su tarjeta, sin recalcular nada:

• health: status (unknown, idle, ok, attention, failing o paused, los estados de la salud de la aplicación), since (desde cuándo está así, o null si nunca se ha evaluado) y title, el nombre corto del estado. Una aplicación desactivada sale como paused aunque el evaluador aún no haya pasado. En la vista de eliminadas llega a null.
• credentialAdvisoryCounts: cuántas recomendaciones de seguridad hay abiertas sobre sus credenciales, en renew (renovar la clave) y updateSdk (actualizar el SDK). El motivo de cada una solo se ve en la ficha.

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.

En el panel, la pantalla Nueva aplicación externa empieza por ¿Para qué la usarás?, con tres opciones: Tickets y soporte, Facturación y cobros y Datos del CRM. Puedes marcar varias o ninguna, y la respuesta no se guarda en la aplicación: solo decide qué más pregunta el formulario y qué permisos te propone al terminar. Toda aplicación nace sin permisos; con usos marcados, la pantalla final te propone juntos los de todos ellos, y sin ninguno te lleva a la pestaña de permisos para que elijas tú. Los ajustes de tickets (cómo se comunica tu equipo con el usuario, la IA y el Proyecto vinculado, que es opcional) solo aparecen, y solo se envían, si marcas Tickets y soporte; si no, la aplicación nace con sus valores por defecto. Las opciones de un aplicativo que tu plan no incluye salen con un candado.

1. Define la identidad de la aplicación

   name y slug son obligatorios. El slug solo admite minúsculas, números y guiones (^[a-z0-9-]+$) y tiene que ser único en tu organización. Si quieres, añade description, logoUrl y websiteUrl.

2. Ajusta la conversación en los dos sentidos y la IA

   Campos opcionales con valores por defecto: allowBidirectional (por defecto true), showAgentNames (por defecto false), customAgentName, aiTranscriptionEnabled (por defecto true) y aiSuggestionsEnabled (por defecto true).

3. Configura orígenes y límites de archivos

   allowedOrigins es la lista de orígenes CORS permitidos. maxFileSize (entre 1 KB y 100 MB) y maxStorageBytes (entre 1 MB y 10 GB) limitan la subida de archivos. Con devProjectId vinculas la aplicación a un proyecto de Gestión de proyectos.

4. Guarda la clave de API y la clave de firma

   La respuesta devuelve apiKeyPlainText y webhookSecretPlainText. 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.

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.

Con dominios autorizados, la clave de la aplicación va en páginas web y solo admite los permisos que se pueden usar desde un navegador. Toda aplicación nace sin permisos, así que el alta con dominios pasa; después, añadir dominios a una aplicación con otros permisos, o concederle uno de fuera, responde 400 SCOPE_NOT_ALLOWED_WITH_ALLOWED_ORIGINS. Por qué y cómo separar la integración en dos aplicaciones está en Claves dentro de una página web.

Detalle y estadísticas

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

El detalle trae además la persona responsable de la aplicación y, si UTILIA OS recomienda renovar alguna de sus claves, esas recomendaciones (credentialAdvisories). El motivo de cada recomendación solo lo ve quien gestiona esa clave.

Configuración de la aplicación

La pantalla Configuración › Ajustes cubre la edición general, la renovación de la clave de API y la activación o desactivación. La clave de firma se renueva en Configuración › Avisos a tu servidor.

El cuerpo de las dos renovaciones admite:

graceDays0 | 1 | 7 | 30

Días que la clave actual sigue valiendo junto a la nueva: 1, 7 o 30, las opciones de la ficha. Con 0, el valor por defecto, deja de valer en el acto. Tiene que ser un número JSON.

twoFactorCodestring

Código de la aplicación de autenticación o de recuperación, si la persona tiene la verificación en dos pasos.

twoFactorApprovalIdstring

Alternativa al código: la confirmación aprobada desde el móvil para esta aplicación, este tipo de clave y estos mismos graceDays.

Las renovaciones no se encadenan: durante una transición, graceDays mayor que 0 responde 409 ROTATION_IN_PROGRESS, y graceDays: 0 hace que la actual y la anterior dejen de valer en el acto. La respuesta trae credentialKind, graceDays, previousValidUntil (hasta cuándo vale la anterior, o null) y rotatedAt, además de la clave nueva. Mientras la clave de API anterior sigue valiendo, las respuestas a las peticiones que la usan llevan la cabecera X-Utilia-Api-Key-Expires con esa fecha.

Desactivar no es eliminar: la aplicación sigue en la lista y se vuelve a activar con el mismo interruptor. Para quitarla de en medio, mira Eliminar una aplicación.

Renovar una clave desde la ficha

La clave de API se renueva en Configuración › Ajustes de la ficha y la clave de firma, en Configuración › Avisos a tu servidor. El diálogo es el mismo para las dos:

1. Elige cuánto sigue valiendo la actual

   1 día, 7 días (recomendado), 30 días o Deja de valer en el acto. Debajo ves hasta qué día y hora valen las dos.

2. Confirma que eres tú

   Si tienes la verificación en dos pasos, con el código de tu aplicación de autenticación o uno de recuperación. Confirmarlo desde el móvil todavía no está en la aplicación de iPhone de la App Store.

3. Copia la clave nueva

   Solo se muestra esta vez. El diálogo no se cierra hasta que pulsas Ya la he guardado.

Durante el periodo de transición no se puede volver a renovar la misma clave: primero hay que retirar la anterior.

• Clave de API: la tarjeta enseña los primeros caracteres de la anterior, hasta cuándo vale y su último uso. Si no se ha usado desde que la renovaste, o hace más de 24 horas, te dice que ya puedes retirarla; si se usó hace menos de una hora, que algún servidor tuyo todavía la usa. Retirar la anterior la deja sin valor en el acto, antes de su fecha.
• Clave de firma: mientras tu servidor sigue con la anterior, la tarjeta ofrece Probar la clave nueva, Mi servidor ya usa la nueva y Retirar la anterior. La prueba envía primero un aviso con una firma falsa y después otro firmado solo con la clave nueva, y dice qué contestó tu servidor a cada uno. El plegable Qué lleva cada aviso y cómo comprobarlo explica las dos cabeceras de firma; el detalle está en Firma HMAC de los avisos.

Quienes gestionan esa clave reciben un aviso cuando otra persona la renueva o retira la anterior antes de su fecha, con la consecuencia para su integración (Avisos de seguridad). Las claves de una aplicación también aparecen en Ajustes › Claves de API, pero allí solo se ven: se gestionan desde la ficha de la aplicación.

Persona responsable

Lo que la aplicación crea o cambia por la API queda a nombre de su persona responsable, que tiene que estar activa: si deja de estarlo y nadie la sustituye, todas las peticiones de la aplicación se rechazan con 403 APP_RESPONSIBLE_INACTIVE.

Lo que la aplicación puede hacer lo deciden sus permisos de la API, no los permisos de esa persona. Los de la persona solo cuentan al emitir rectificativas, al gestionar suscripciones y cobros programados (si le falta el permiso, 403 APP_RESPONSIBLE_PERMISSION_DENIED) y en las escrituras del chat. Por eso, con el permiso de la API, una aplicación lee y escribe los clientes, contactos y leads de toda la organización aunque su responsable solo vea los suyos. El detalle está en La persona responsable.

En la ficha, el bloque Información del Resumen enseña quién es la persona responsable. Un Super Administrador elige a cualquiera con Elegir responsable; el resto solo puede Nombrarme responsable, y la ficha lo explica: «Solo un Super Administrador puede nombrar responsable a otra persona». La persona nombrada, la anterior y quienes gestionan la aplicación reciben un aviso.

Recomendaciones de renovar una clave

Si UTILIA OS recomienda renovar una clave de la aplicación, la ficha lo muestra en una banda con el plazo recomendado y el botón para renovarla. Quien gestiona esa clave puede descartar la recomendación con un motivo:

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 de Configuración › Ajustes 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.

Cada entrada del catálogo incluye:

Sobre la actualización (PATCH .../scopes):

• scopes lleva la lista completa que debe quedar, no solo los cambios. El servidor calcula added y removed.
• 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 es 409.
• 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.

400 SCOPE_NOT_ALLOWED_WITH_ALLOWED_ORIGINSerror

La clave de la aplicación está publicada en páginas web y el permiso no se puede usar con ella. notAllowedScopes dice cuáles.

403 RESPONSIBLE_SELF_ONLYerror

Ampliar los permisos solo lo puede hacer la persona responsable de la aplicación o un Super Administrador. Quitarlos, cualquiera con EXTERNAL_APPS_EDIT.

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.

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

El cuerpo es opcional y decide qué prueba se hace:

• Sin cuerpo, o con {"event": "WEBHOOK_TEST"}: Probar la conexión, un aviso de prueba firmado igual que los de verdad.
• {"secret": "current"}: Probar la clave nueva. Primero un aviso con una firma falsa, que tu servidor debería rechazar, y después otro firmado solo con la clave vigente. La respuesta trae el resultado de los dos y un veredicto (verdict): si tu servidor acepta el de la firma falsa, el mensaje lo dice, porque significa que no está comprobando la firma.
• {"event": "INVOICE_CREATED"} (o cualquier otro evento del catálogo que el plan de tu organización permita suscribir): una muestra de ese evento, firmada igual que los avisos reales, con livemode: false, meta.test: true e identificadores inventados que llevan test. Las de los eventos de facturación, de métodos de pago (PAYMENT_METHOD_ADDED y PAYMENT_METHOD_REMOVED) y de salud (APP_HEALTH_CHANGED) tienen la forma exacta de los reales. La respuesta añade el evento, si la aplicación está suscrita a él (subscribed), si la muestra es exacta o genérica (sampleShape), el cuerpo enviado (payload) y el principio de la respuesta de tu servidor (responseSnippet). Es lo que usa la pestaña Pruebas.

Si llegan secret y event, manda secret. Ninguna prueba queda en el historial de entregas ni se reintenta, y cada una espera la respuesta de tu servidor como mucho 10 segundos (la entrega real espera 30).

La prueba responde 400 WEBHOOK_NO_URL si la aplicación no tiene dirección configurada, 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), 400 VALIDATION_ERROR si event no está en el catálogo, 403 MODULE_NOT_ENABLED si el plan no incluye el aplicativo del evento y, al probar la clave nueva, 409 WEBHOOK_SECRET_NOT_CONFIGURED si no hay clave. Con los avisos desactivados no sale nada: el resultado lo dice con success: false (al probar la clave nueva, con un 409). 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

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.

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

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.

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.

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; 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).

La revisión solo se acepta si la factura tiene número y su PDF original (y su código QR, si lo lleva) está generado y verificado; si no, o si la emisión sigue en curso, responde 409 INVOICE_STATE_INVALID. No reemite ni envía nada: deja la emisión en complete, queda en el registro de auditoría con quien la hizo y responde {"status": "complete"}, también si ya estaba completa. Desde ese momento la aplicación puede rectificar o anular la factura. Ver Estado de la emisión.

Series por defecto de la aplicación

Una aplicación puede numerar sus facturas en una serie propia (por ejemplo, APP-202600001), separada de la de las facturas del equipo. La serie se crea en Ajustes › Organización, necesitas entrar con tu cuenta, pestaña Facturas, bloque Series de facturación, con el permiso «Editar organización», eligiendo la aplicación a la que se reserva. Después, en la pantalla Facturación de la aplicación (o con PATCH :id/billing-config), se fija la serie por defecto:

defaultStandardSeriesIdstring | null

Serie de las facturas ordinarias que la aplicación emite sin seriesCode: una serie de ordinarias, activa y reservada a esta aplicación. null vuelve a la serie general de siempre.

defaultSimplifiedSeriesIdstring | null

Serie de las simplificadas que la aplicación emite sin seriesCode: una serie de simplificadas, activa y reservada a esta aplicación. null vuelve a la de siempre (T-).

availableSeriesarray

Solo en la lectura (GET): las series activas reservadas a la aplicación, con id, code, prefix, documentType y description. Son las únicas que se pueden fijar por defecto.

Una serie que no es de la organización, de otra aplicación o del equipo responde 400 INVOICE_SERIES_NOT_AVAILABLE; una de otro tipo, 400 INVOICE_SERIES_TYPE_MISMATCH, y una desactivada, 409 INVOICE_SERIES_INACTIVE. El cambio queda en el registro de auditoría con el antes y el después. Fijar la serie no exige ser Super Administrador: no amplía lo que la aplicación puede hacer, solo dónde se numera. Mientras sea la serie por defecto de una aplicación, la serie no se puede desactivar (409 INVOICE_SERIES_IN_USE): primero hay que cambiar la de la aplicación. La aplicación ve sus series con GET /external/v1/invoices/series, pero la clave de API no puede crearlas ni cambiarlas.

El recorrido completo, de la primera factura al cobro recurrente, está en Facturar y cobrar desde tu aplicación.

Eliminar una aplicación

Hay dos formas de quitar una aplicación, las dos con el permiso «Eliminar aplicaciones externas» (EXTERNAL_APPS_DELETE) y las dos al final del menú de su ficha, en rojo y separadas del resto:

Dos formas de eliminar

Se puede deshacer

Eliminar

Deja de funcionar en el acto y desaparece de la lista, pero no se borra nada. Se restaura desde Eliminadas y vuelve desactivada.

No se puede deshacer

Eliminar definitivamente

Borra la aplicación y lo que solo es suyo. Lo que la ley obliga a guardar se queda, ya sin el vínculo. Se confirma escribiendo su nombre.

Estados de una aplicación externa

1. Activa

   Su clave funciona y recibe avisos.

   • Se llega desde Activa cuando: DELETE :id

     Eliminada

     No funciona ni sale en la lista; se conserva todo.

     • Se llega desde Eliminada cuando: POST :id/permanent-delete

       Eliminada definitivamente

       Estado final

       Ya no existe; lo que obliga la ley se queda.

2. Se llega desde Activa cuando: PATCH :id/active

   Desactivada

   Sigue en la lista; su clave responde 403 APP_DISABLED.

Otras transiciones

• Desactivada → pasa a Activa: PATCH :id/active la vuelve a activar.
• Desactivada → pasa a Eliminada: DELETE :id también elimina una desactivada.
• Eliminada → pasa a Desactivada: POST :id/restore la devuelve, siempre desactivada.
• Activa → pasa a Eliminada definitivamente: POST :id/permanent-delete no exige eliminarla antes.

Eliminar

Al eliminarla, en el acto:

• su clave de API deja de valer y la API externa responde 401 API_KEY_INVALID, y se cierran las conexiones abiertas con ella;
• deja de recibir avisos nuevos en tu servidor;
• se apagan su inicio de sesión con OAuth y su ficha del catálogo de aplicaciones, si la tenía;
• su identificador (slug) queda reservado, porque sus tickets lo llevan en el código: dar de alta o renombrar otra aplicación con él responde 409 EXTERNAL_APP_SLUG_HELD_BY_DELETED.

No se puede eliminar mientras cobra: con suscripciones activas o en pausa o con cobros programados pendientes, la respuesta es 409 EXTERNAL_APP_HAS_ACTIVE_BILLING, con details.activeSubscriptions y details.pendingScheduledCharges. Primero hay que dar de baja esas suscripciones y cancelar esos cobros. Una aplicación de otra organización o que ya estaba eliminada responde 404.

Ver las eliminadas y restaurar

En el listado del panel, la pestaña Eliminadas (solo para quien puede eliminar) enseña cada aplicación eliminada con la fecha y dos botones, Restaurar y Eliminar definitivamente. Por la API es GET /api/integrations/apps?deleted=only.

Al restaurarla vuelven su clave de API y su ficha del catálogo, pero la aplicación queda desactivada: hasta que alguien la active (PATCH :id/active con {"active": true}), su clave responde 403 APP_DISABLED. El inicio de sesión con OAuth no se enciende solo, para que no vuelvan a valer los tokens que había antes de eliminarla: si la aplicación lo usaba, vuelve a activarlo en Configuración › Inicio de sesión.

Eliminar definitivamente

Antes de borrar, el panel te enseña qué se borra, qué se conserva y qué lo impide:

confirmNamestring (1 a 200)obligatorio

El nombre de la aplicación, escrito tal cual para confirmar. Se compara sin los espacios del principio y del final; si no coincide, 400 CONFIRMATION_MISMATCH.

Se borra: la aplicación, sus usuarios (y sus accesos a facturas y tarjetas cuando no tienen ficha de cliente), los mensajes que publicó en el chat (las respuestas de las personas se quedan), sus accesos a canales, el historial de avisos enviados, sus métricas de uso, su cliente OAuth con sus tokens y su clave de API.

Se conserva, sin el vínculo con la aplicación: las facturas y las rectificativas, las suscripciones, las autorizaciones de cobro, los tickets, las fichas del CRM que creó, los archivos que subió y sus series de facturación, que quedan desactivadas con su código y su numeración.

Si algo lo impide, la respuesta es 409 EXTERNAL_APP_PERMANENT_DELETE_BLOCKED y details.blockers trae cada motivo con su code, su message y, si se sabe, su count:

Por MCP

La herramienta integrations hace lo mismo con apps_delete, apps_restore y apps_delete_permanently, con el permiso EXTERNAL_APPS_DELETE y el scope integrations:apps:manage. Las tres piden confirm: true, y el borrado definitivo, además, confirmName. Las eliminadas se listan con apps_list y deletedOnly: true. Detalle en la referencia MCP.

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.

400 CONFIRMATION_MISMATCHerror

Al eliminarla definitivamente, confirmName no es el nombre exacto de la aplicación.

404error

La aplicación no existe en tu organización o, para casi todo salvo restaurarla y eliminarla definitivamente, está eliminada.

409error

Slug repetido al crear o reservado por una aplicación eliminada, conflicto de bloqueo optimista en los permisos, aplicación desactivada, o algo que impide eliminarla (EXTERNAL_APP_HAS_ACTIVE_BILLING) o eliminarla definitivamente (EXTERNAL_APP_PERMANENT_DELETE_BLOCKED).

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.

Siguiente paso

• Permisos de la APICatálogo completo por áreas y reglas de concesión.
• Avisos a tu servidorCatálogo de eventos, contenido y firma.
• Probar y diagnosticarEl diagnóstico, la prueba de lectura y la salud de tu integración.
• Iniciar sesión con UTILIAOAuth para actuar en nombre de una persona.