Primeros 15 minutos con la API

Esta guía te lleva de cero a una integración que funciona: das de alta la aplicación, le concedes permisos, identificas a un usuario, abres un ticket en su nombre, pides sugerencias de IA y aprendes a tratar los errores sin que tu interfaz se rompa.

Necesitas la clave de API de una aplicación externa. Los ejemplos usan tickets de soporte, así que el plan de tu organización tiene que incluir el aplicativo Tickets de soporte con la capacidad «Tickets propios», además de Integraciones.

Esta es la conversación completa entre tu servidor y UTILIA OS; los pasos de abajo la construyen una petición cada vez:

1. Crea la aplicación y guarda su clave

   Cada integración necesita su propia aplicación externa. Créala desde Ajustes › Integraciones › Aplicaciones externas, necesitas entrar con tu cuenta con Crear app y elige «Tickets y soporte» como uso. Al terminar verás la clave de API, del tipo utl_xxxxxxxxxxxxxxxx, que enviarás en cada petición:

   HTTP

   X-Api-Key: utl_xxxxxxxxxxxxxxxx

   La clave es secreta: úsala desde tu servidor, nunca en el navegador ni en el repositorio. El alta paso a paso está en Panel de aplicaciones externas.

2. Concede los permisos

   La aplicación nace sin permisos. En su ficha, Ajustes › Permisos, aplica el conjunto «Tickets y soporte», que concede:

   • crm:users:read y crm:users:write, para listar y dar de alta usuarios.
   • support:tickets:read y support:tickets:write, para leer y abrir tickets.

   Si vas a seguir los pasos de IA y de errores, añade a mano «IA en tickets de soporte» (support:tickets:ai) y «Reportar errores al backend» (analytics:errors:write).

3. Identifica al usuario final

   Antes de crear tickets, pedir IA o emitir facturas para un usuario, llama a POST /users/identify. Es el paso que vincula tu usuario con UTILIA OS mediante un externalId que tú eliges.

   Casi todos los endpoints que reciben userId en la dirección o como campo suelto del cuerpo dan por hecho que el usuario ya existe; si no, responden 404 con errorCode: USER_NOT_FOUND. Las excepciones son los que aceptan un objeto user: { externalId, email, name } en el cuerpo, como POST /tickets y POST /invoices: crean el usuario si no existe y lo actualizan si ya existe.

   curlfetchPython

   curl -X POST 'https://os.utilia.ai/api/external/v1/users/identify' \
     -H 'Content-Type: application/json' \
     -H 'X-Api-Key: utl_xxx' \
     -d '{
       "externalId": "user_42",
       "email": "ada@example.com",
       "name": "Ada Lovelace"
     }'

   Llama a identify cuando el usuario inicia sesión en tu aplicación y otra vez si cambian su correo o su nombre. Detalle en Usuarios externos.

   Con el SDK de JavaScript o de Python, identifica al usuario de forma explícita con sdk.users.identify(...) antes de operar sobre él: el SDK no lo hace por ti. Ver la configuración del SDK de JavaScript o del SDK de Python.

4. Abre un ticket

   Tienes dos formas equivalentes de crear el ticket. Elige la que mejor encaje con tu flujo:

   Opción A: deja que el propio endpoint cree el usuario. No necesita identify previo: UTILIA OS busca al usuario por la pareja aplicación más externalId y lo crea si no existe.

   fetchPython

   const res = await fetch('https://os.utilia.ai/api/external/v1/tickets', {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
       'X-Api-Key': 'utl_xxx',
     },
     body: JSON.stringify({
       user: {
         externalId: 'user_42',
         email: 'ada@example.com',
         name: 'Ada Lovelace',
       },
       title: 'No puedo subir archivos al panel',
       description: 'Recibo un timeout al intentar adjuntar el PDF de la factura.',
       category: 'BUG',
       priority: 'ALTA',
       context: { url: 'https://mi-app.com/facturas/123' },
     }),
   });
   const ticket = await res.json();

   Opción B: si ya llamaste a /users/identify, envía solo user.externalId. Los datos que omitas no se sobrescriben.

   Todos los campos del ticket están en Endpoints básicos de tickets.

5. Pide sugerencias de IA

   La IA analiza el texto, el audio o las imágenes que escribe tu usuario y propone title, description, category y priority para el ticket. A diferencia de POST /tickets, POST /tickets/ai-suggest no crea el usuario: el userId del cuerpo tiene que existir ya, o la respuesta es 404 con USER_NOT_FOUND.

   fetchPython

   // 1. Solicitar sugerencias (devuelve un jobId)
   const enqueue = await fetch(
     'https://os.utilia.ai/api/external/v1/tickets/ai-suggest',
     {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
         'X-Api-Key': 'utl_xxx',
       },
       body: JSON.stringify({
         userId: 'user_42', // debe estar previamente identificado
         text: 'No puedo subir archivos. Sale un timeout cuando adjunto el PDF.',
         existingFields: { title: '', description: '' },
         source: 'SDK_EXTERNAL',
       }),
     },
   );
   const { jobId } = await enqueue.json();
    
   // 2. Recibir el resultado en tiempo real (o consultando el estado).
   //    EventSource no puede enviar cabeceras, así que la clave viaja como
   //    parámetro `apiKey` (solo se acepta en peticiones GET de eventos).
   const eventSource = new EventSource(
     `https://os.utilia.ai/api/external/v1/tickets/ai-suggest/${jobId}/stream?apiKey=utl_xxx`,
   );
   eventSource.onmessage = (msg) => {
     const data = JSON.parse(msg.data);
     if (data.event === 'completed') {
       console.log('Sugerencias:', data.result.suggestions);
       eventSource.close();
     }
   };

   Opciones de audio e imágenes en Endpoints de sugerencias con IA.

6. Envía los errores de tu aplicación

   UTILIA OS tiene dos endpoints distintos para errores, y confundirlos es de lo más habitual al integrar.

   Endpoint	Para qué sirve	Quién lo llama	Campos
   POST /errors/report	Errores de la lógica de negocio de tu aplicación que quieres registrar con contexto (módulo, archivo, línea, función, usuario, contexto)	Tu servidor	message y module (obligatorios), y además severity, stack, file, line, function, endpoint, method, userId, requestId, context
   POST /tickets/client-errors	Errores del navegador que envían el SDK o el widget, en lotes de hasta 10	Tu interfaz web, o el SDK por su cuenta	errors[] con message, stack, code, severity, endpoint, method, requestId, component, url, userAgent

   Regla práctica: si lo llamas tú desde tu servidor para registrar un error con contexto, POST /errors/report; si son errores del navegador en lote, POST /tickets/client-errors. Detalle en Endpoints de errores de tu aplicación y Endpoint de errores del cliente.

7. Trata los errores en tu interfaz

   Cuando algo falla, UTILIA OS responde siempre con la misma forma:

   JSON

   {
     "statusCode": 404,
     "message": "Usuario externo no encontrado. Usa /users/identify primero.",
     "error": "NOT_FOUND",
     "errorCode": "USER_NOT_FOUND",
     "timestamp": "2026-05-07T10:31:12.000Z",
     "requestId": "550e8400-e29b-41d4-a716-446655440000"
   }

   No pases el cuerpo del error a tu interfaz

   error.response.data es un objeto, no un texto. Si lo pintas con toast.error(error.response.data) o lo metes como hijo en JSX, React lanza «Objects are not valid as a React child» y la pantalla se rompe. Muestra message, decide con errorCode y guarda requestId para soporte.

   La receta completa está en Errores, identificador de petición y reintentos.

8. Recibe avisos en tu servidor

   Para enterarte de lo que pasa sin preguntar (una respuesta en un ticket con TICKET_REPLIED, su resolución con TICKET_RESOLVED, un usuario nuevo con USER_CREATED), configura la dirección de avisos en la pestaña Avisos a tu servidor de la ficha y comprueba la firma de cada entrega. Es opcional, pero ahorra muchas consultas.

   Catálogo de eventos y firma en Avisos a tu servidor: visión general.

Errores típicos en la primera integración

Siguiente paso

• Repasa Dónde va cada parámetro: es la causa número uno de errores 400 y 404 en las primeras integraciones.
• Si vas a emitir facturas, sigue la guía de facturación y cobro.
• Antes de pasar a producción, vigila tu integración desde Métricas de la API.