# Por dónde empezar a integrar Cuatro caminos según lo que construyes: automatizar tu empresa, tu producto con sus usuarios, conectar una IA o una aplicación para todas las empresas. 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 **¿Qué quieres construir?** ¿Para quién es lo que vas a construir? - Para mi propia empresa: **Automatizar tu empresa** (`Authorization: Bearer utk_…`). Scripts, cuadros de mando y procesos con los datos de tu organización. - Para los usuarios de mi app: **Tu producto con sus usuarios** (`X-Api-Key: utl_…`). Soporte, archivos, facturas y cobros de las personas que usan tu producto. - Para un asistente de IA: **Conectar una IA** (`MCP + OAuth`). Claude, ChatGPT o Cursor trabajando con tus datos y tus permisos. - Para todas las empresas: **Una aplicación para todas** (`Una clave por instalación`). Que cualquier empresa de UTILIA OS la instale desde el catálogo. _Cada camino lleva a su apartado de esta página._ Si dudas entre dos credenciales, [Elegir credencial](https://os.utilia.ai/docs/developers/getting-started/choose-credential) 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](https://os.utilia.ai/docs/developers/organization-api-keys/first-request). 3. Si prefieres que lo haga un asistente de IA, el camino es [Conectar una IA](#conectar-una-ia). La sección completa es [Claves de API de la organización](https://os.utilia.ai/docs/developers/organization-api-keys/overview). ## 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](https://os.utilia.ai/docs/developers/getting-started/quickstart). 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](https://os.utilia.ai/docs/developers/getting-started/testing-quickstart). 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](https://os.utilia.ai/docs/developers/webhooks/overview), los [SDK de JavaScript y Python](https://os.utilia.ai/docs/developers/sdk/overview), el [widget de soporte](https://os.utilia.ai/docs/developers/widget/overview) y, si tu aplicación factura, la [guía de facturación y cobro](https://os.utilia.ai/docs/developers/api/billing-guide). ## 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](https://os.utilia.ai/docs/developers/mcp/quickstart). Quien usa la aplicación lo tiene explicado en [Conecta tu IA](https://os.utilia.ai/docs/guides/connect-ai/overview). - Para que un asistente de programación escriba tu integración, dale [Integrar con un asistente de IA](https://os.utilia.ai/docs/developers/getting-started/ai-assistants) 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](https://os.utilia.ai/docs/developers/console/overview), 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](https://os.utilia.ai/docs/developers/apps-platform/overview), y si quieres cobrar por ella, [Precio y cobros](https://os.utilia.ai/docs/developers/pricing-and-payouts/overview). 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](https://os.utilia.ai/docs/developers/oauth/overview). > **Atención: Cualquier persona puede autorizar tu cliente** > > Un cliente OAuth creado con el registro dinámico lo puede autorizar cualquier persona con cuenta en UTILIA OS, sea de la empresa que sea. Si tu aplicación no es para todo el mundo, filtra tú quién entra con el claim `org_id`, que dice de qué organización es la persona: lo cuenta [Quién puede autorizar tu aplicación](https://os.utilia.ai/docs/developers/oauth/apps-panel#quién-puede-autorizar-tu-aplicación). ## 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](https://os.utilia.ai/docs/developers/getting-started/errors-and-retries). - **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](https://os.utilia.ai/docs/developers/getting-started/errors-and-retries#repetir-sin-duplicar-idempotencykey). ## Para tu código y tu IA La documentación también se lee sin navegador: | Qué | Dónde | | - | - | | Contrato OpenAPI 3 de la API externa, sin clave | `https://os.utilia.ai/docs/openapi/external-v1.json` | | Índice de toda la documentación para asistentes | `https://os.utilia.ai/llms.txt` | | Texto completo de una sección, como la de la API | `https://os.utilia.ai/docs/developers/api/llms-full.txt` | | Cualquier página en Markdown | Su dirección con `.md` al final, como `https://os.utilia.ai/docs/developers/getting-started/overview.md` | 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](https://os.utilia.ai/docs/developers/changelog/versioning). ## Siguiente paso - [Elegir credencial](https://os.utilia.ai/docs/developers/getting-started/choose-credential): Las seis credenciales y cuál te toca según quién llama. - [Primeros 15 minutos con la API](https://os.utilia.ai/docs/developers/getting-started/quickstart): Identifica a un usuario, abre un ticket y pide sugerencias de IA.