Por dónde empezar a integrar

UTILIA OS se conecta con tu software por cuatro caminos, y cada uno tiene su credencial, su API y su primera página. Elige el tuyo por lo que quieres construir, no por la tecnología: el resto de la documentación cuelga de aquí.

Elige tu camino

Si dudas entre dos credenciales, Elegir credencial las compara con un árbol de decisión.

Automatizar tu empresa

Para un script, un cuadro de mando o una automatización en tu servidor con los datos de tu propia organización, usa una clave de API de la organización (utk_…). Actúa con los permisos de una persona de tu equipo, nunca con más, y abre las mismas rutas que usa la aplicación.

1. Créala en Ajustes, Claves de API, con el tipo «Acceso a la API».
2. Compruébala con su primera petición: Tu primera petición.
3. Si prefieres que lo haga un asistente de IA, el camino es Conectar una IA.

La sección completa es Claves de API de la organización.

Tu producto con sus usuarios

Si tienes una aplicación propia y quieres que sus usuarios abran tickets, suban archivos o reciban facturas de tu organización, crea una aplicación externa. Su clave (utl_…, en la cabecera X-Api-Key) abre la API externa (/api/external/v1), un contrato estable y versionado, y la aplicación recibe avisos firmados en tu servidor cuando algo cambia.

1. En Ajustes, Creadas por tu empresa, pulsa Nueva aplicación y guarda sus dos claves: la de API y la de firma de los avisos. Se muestran una sola vez.
2. Concédele los permisos de la API que vaya a usar: nace sin ninguno.
3. Haz tu primera llamada: Primeros 15 minutos con la API. Si algo no responde como esperas, GET /api/external/v1/diagnostics te dice qué puede hacer tu clave y qué le falta: lo explica Probar tu integración.

Necesitas el aplicativo Integraciones en el plan y los permisos «Crear aplicaciones externas» y «Editar aplicaciones externas». Después vienen los avisos a tu servidor, los SDK de JavaScript y Python, el widget de soporte y, si tu aplicación factura, la guía de facturación y cobro.

Conectar una IA

Un asistente de IA se conecta a UTILIA OS por MCP, con el inicio de sesión de la persona que lo usa: trabaja con sus permisos y dentro del plan de su organización, sin claves que copiar.

• Para conectar Claude, ChatGPT o Cursor a tus datos, sigue Primeros pasos con MCP. Quien usa la aplicación lo tiene explicado en Conecta tu IA.
• Para que un asistente de programación escriba tu integración, dale Integrar con un asistente de IA y los textos de esta documentación de la lista siguiente.

Una aplicación para todas las empresas

Si quieres que cualquier empresa de UTILIA OS use tu aplicación, publícala en el catálogo de aplicaciones. Se publica desde la consola de desarrolladores, con una cuenta de desarrollador aparte de tu empresa, gratis y con empresas de prueba para probarla. Cada empresa la instala desde Ajustes, Aplicaciones, Explorar, acepta los permisos que pide tu ficha y elige con qué persona actuará; tu servidor recibe entonces la clave de API y la clave de firma de esa instalación, una por empresa, sin que nadie las copie. Lo explica la sección Plataforma de aplicaciones, y si quieres cobrar por ella, Precio y cobros.

Si tu aplicación trabaja en nombre de cada persona que la usa, con su cuenta, el camino es Iniciar sesión con UTILIA: una persona de cualquier organización la autoriza y tu aplicación trabaja con sus datos por MCP, con sus permisos. Lo explica OAuth: visión general.

Lo que vale para todos

• La clave nunca sale de tu servidor, salvo la de una aplicación con dominios autorizados, que solo admite los permisos del navegador.
• Dos puertas antes de cada operación. Primero el plan de la organización (403 MODULE_NOT_ENABLED o CAPABILITY_NOT_ENABLED, que reintentar no arregla); después el permiso de la credencial (403 INSUFFICIENT_SCOPE, con el que falta en requiredScopes).
• Lo que no está a tu alcance responde 404, nunca 403, para no revelar que existe.
• Cada error dice quién lo arregla y dónde está explicado, en fixedBy y docsUrl, y cada respuesta lleva X-Request-Id para soporte. Lo detalla Errores, identificador de petición y reintentos.
• Repetir sin duplicar es posible en las operaciones que llevan idempotencyKey en el cuerpo, como emitir una factura o un cobro. Las demás no se deben repetir a ciegas: lo explica Repetir sin duplicar.

Para tu código y tu IA

La documentación también se lee sin navegador:

El contrato OpenAPI sale del mismo código que valida cada petición y se publica con cada versión. Sirve para generar un cliente, importarlo en Postman o dárselo a un asistente antes de tener una clave. La API externa es estable en su versión 1: lo explica Versionado de la API externa.

Siguiente paso

• Elegir credencialLas seis credenciales y cuál te toca según quién llama.
• Primeros 15 minutos con la APIIdentifica a un usuario, abre un ticket y pide sugerencias de IA.