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 en Ajustes, Creadas por tu empresa con Nueva aplicación, marca «Tickets y soporte» en «¿Para qué la usarás?» y pulsa Crear la aplicación. 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 y no la subas nunca al repositorio. Si una web tuya tiene que llamar a la API desde el navegador, como el widget de soporte, usa otra aplicación con dominios autorizados y solo los permisos del navegador; lo explica Claves dentro de una página web. El alta paso a paso está en Panel de aplicaciones externas.

2. Concede los permisos

   La aplicación nace sin permisos. En su ficha, Configuración › Ajustes, pestaña 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 «Enviar errores de la aplicación» (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

   // En tu servidor, con la clave:
   // 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: tu servidor pide un pase de un
   //    solo uso con la clave en la cabecera...
   const pase = await fetch('https://os.utilia.ai/api/external/v1/tickets/stream-token', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json', 'X-Api-Key': 'utl_xxx' },
     body: JSON.stringify({ route: 'ai-suggest', jobId }),
   }).then((r) => r.json());
    
   // ...y el navegador abre la conexión solo con el pase, nunca con la clave.
   const eventSource = new EventSource(
     `https://os.utilia.ai/api/external/v1/tickets/ai-suggest/${jobId}/stream?streamToken=${pase.streamToken}`,
   );
   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

   Con el SDK, la captura son dos líneas: sdk.errors.install() al arrancar, que recoge sola lo que nadie trata, y sdk.errors.capture(error) donde ya atrapas un error. Nunca lanzan y envían en lotes (Capturar los errores de tu aplicación).

   Sin el SDK, hay dos endpoints distintos, y confundirlos es de lo más habitual al integrar:

   Endpoint	Para qué sirve	Quién lo llama	Campos
   POST /errors/report y POST /errors/batch	Los errores de tu aplicación, con contexto, uno a uno o en lotes de hasta 25	Tu servidor, o el SDK con install y capture	message y module (obligatorios), y además severity, stack, file, line, function, endpoint, method, userId, requestId, context, release, environment, fingerprint y tags
   POST /tickets/client-errors	Los fallos del propio widget y de ai.reportError, en lotes de hasta 10	El widget y el SDK	errors[] con message, stack, code, severity, endpoint, method, requestId, component, url, userAgent, release y environment

   Regla práctica: los errores de tu aplicación van a /errors/report o /errors/batch; /tickets/client-errors es la telemetría ligera del widget. Detalle en Enviar los errores de tu aplicación y Telemetría ligera del widget y del SDK.

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 Configuración › Avisos a tu servidor, en 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 y, antes de la primera real, compruébalo todo sin emitir nada con Probar la facturación sin emitir facturas.
• Antes de pasar a producción, vigila tu integración desde la pestaña de métricas de su ficha: lo explica Métricas de la API.