Por dónde empezar a integrar

Con la clave de API de una aplicación externa, tu software puede abrir tickets, sincronizar el CRM, facturar y cobrar en UTILIA OS. Esta página te lleva de cero a tu primera respuesta y te explica las cuatro reglas que valen para todas las llamadas.

UTILIA OS se integra con tu software por tres caminos que casi siempre se usan juntos: tu aplicación llama a la API, UTILIA OS te avisa cuando algo cambia y una persona autoriza desde su sesión lo que necesita su firma.

Tu primera petición en cinco minutos

Para el primer paso, abre Ajustes › Integraciones › Aplicaciones externas, necesitas entrar con tu cuenta. Al crear la aplicación, copia sus dos claves en un sitio seguro: la clave de API identifica a tu aplicación en cada petición y la clave de firma sirve para comprobar que un aviso viene de UTILIA OS. Si pierdes una, puedes regenerarla desde la ficha de la aplicación. La aplicación nace sin ningún permiso, por eso el segundo paso es imprescindible.

Toda la API cuelga de https://os.utilia.ai/api y la API externa vive en /external/v1. La llamada del tercer paso es esta:

curl 'https://os.utilia.ai/api/external/v1/users?limit=1' \
  -H 'X-Api-Key: utl_tu_clave'

Si todo está bien, recibes un 200 con la lista de usuarios externos de tu aplicación (vacía mientras no des de alta ninguno):

{
  "users": [],
  "pagination": { "page": 1, "limit": 1, "total": 0, "totalPages": 0 }
}

El recorrido completo, con el alta de un usuario y la apertura de un ticket, está en Primeros 15 minutos con la API.

Cuatro reglas que valen para todas las llamadas

La clave nunca sale de tu servidor. Tiene todos los permisos de la aplicación, incluidos los que mueven dinero. No la pongas en el navegador ni en el repositorio de código.

Hay dos puertas antes de cada operación. Primero el plan de la organización: si el aplicativo o la capacidad no están contratados, la respuesta es 403 con errorCode MODULE_NOT_ENABLED o CAPABILITY_NOT_ENABLED. Es una decisión comercial, no un fallo técnico, y reintentar no lo arregla. Después, el permiso de la aplicación: si no lo tiene concedido, 403 con INSUFFICIENT_SCOPE y un mensaje que no dice cuál falta.

Cada aplicación solo ve lo suyo. Los listados se acotan a la aplicación que llama y, cuando la llamada trae un usuario, a ese usuario. Dos aplicaciones de la misma organización no se ven entre sí. Lo que no es tuyo responde 404, nunca 403, para no revelar que existe.

Puedes repetir sin duplicar. Las creaciones que mueven dinero o emiten un documento (facturas, suscripciones, cobros) aceptan una clave de idempotencia válida 24 horas: repetir la misma clave devuelve el resultado de la primera llamada.

Errores que verás al empezar

Cada respuesta de la API lleva la cabecera X-Request-Id. Guárdala en tus registros: es lo que necesita soporte para encontrar tu petición. El detalle de cada error está en Errores, identificador de petición y reintentos.

Elige tu camino

• API RESTLas rutas de /external/v1, con la clave de tu aplicación. Es el camino principal.
• SDK de JavaScript y PythonLos mismos endpoints, con tipos, validación local y reintentos.
• Avisos a tu servidorUTILIA OS llama a tu dirección cuando algo cambia, con firma y reintentos.

Si lo que quieres es facturar y cobrar desde tu aplicación, que es el caso que más piezas encadena (identificar al usuario, guardar su tarjeta, recoger su autorización, emitir la factura y cobrar sin nadie delante), sigue la guía de facturación y cobro y, para entender cómo encajan las piezas, la arquitectura de la facturación.

La API externa es estable en su versión 1 y crece sin romper lo que ya funciona; los SDK tienen su propio versionado. Lo explica Versionado de la API externa.

Siguiente paso

• Primeros 15 minutos con la APIIdentifica a un usuario, abre un ticket y pide sugerencias de IA.
• Autenticación con clave de accesoCómo valida la API tu clave y cuándo la acepta en la dirección.
• Permisos de la APIEl catálogo de permisos, sus categorías y su recorte por plan.
• Panel de aplicaciones externasDónde se configura todo esto dentro de UTILIA OS.