Instalar el SDK
Requisitos, instalación con npm o pip y primera llamada del SDK de UTILIA OS en JavaScript y en Python.
Actualizado el . 2 min de lectura
Incluido en todos los planes. Ver precios
Esta página te lleva de cero a la primera llamada: instalas el paquete de tu lenguaje, creas el cliente con la clave de tu aplicación externa e identificas a un usuario para abrirle un ticket de soporte. Los ejemplos de código están en pestañas; elige tu lenguaje una vez y la documentación lo recordará en todas las páginas.
Requisitos
| JavaScript | Python | |
|---|---|---|
| Paquete | @utilia-os/sdk-js | utilia-sdk |
| Versión del lenguaje | Node.js 18 o superior | Python 3.9 o superior |
| Dependencias que se instalan solas | axios | httpx y pydantic 2 |
Necesitas además la clave de acceso de tu aplicación externa, que empieza por utl_. Se obtiene al dar de alta la aplicación: el proceso está en Panel de aplicaciones externas.
La clave no sale de tu servidor
La clave utl_ lleva todos los permisos de la aplicación, también los que mueven dinero. Úsala solo en código de servidor: nunca en el navegador ni en una aplicación móvil.
Instalación
npm install @utilia-os/sdk-jsEn Python conviene instalarlo dentro de un entorno virtual (python -m venv .venv y, después, source .venv/bin/activate).
Primera llamada
Es el recorrido mínimo para comprobar que la clave y la dirección base funcionan:
Tu primera llamada, paso a paso
UtiliaSDK
Crear el cliente
Con la dirección base y la clave utl_ de tu aplicación.addMessage y close
Responder y cerrar
Añade un mensaje y cierra el ticket.
import { UtiliaSDK } from '@utilia-os/sdk-js';
const sdk = new UtiliaSDK({
baseURL: 'https://os.utilia.ai/api',
apiKey: process.env.UTILIA_API_KEY!, // utl_...
});
// 1. Identificar al usuario (lo crea o lo actualiza)
const user = await sdk.users.identify({
externalId: 'usr-4821',
email: 'laura.garcia@ejemplo.com',
name: 'Laura García',
});
// 2. Abrir un ticket de soporte
const ticket = await sdk.tickets.create({
user: { externalId: 'usr-4821' },
title: 'No puedo acceder a mis facturas',
description: 'Al entrar en la sección de facturación aparece un error 500.',
category: 'CONSULTA',
priority: 'ALTA',
});
console.log(ticket.ticketKey); // por ejemplo, APP-0001
// 3. Añadir un mensaje y cerrar el ticket
await sdk.tickets.addMessage(ticket.id, 'usr-4821', {
content: 'Adjunto captura del error.',
});
await sdk.tickets.close(ticket.id, 'usr-4821');Python asíncrono o síncrono
El SDK de Python trae dos clases con los mismos servicios y los mismos métodos:
Dos clases para Python
Asíncrono
UtiliaSDK
Síncrono
UtiliaSDKSync
Los ejemplos de esta documentación usan la clase asíncrona. Para la síncrona, cambia UtiliaSDK por UtiliaSDKSync, async with por with y quita los await.
Las dos abren una sesión HTTP que hay que cerrar al terminar. Con async with o with se cierra sola; si creas el cliente sin ese bloque, llama tú a await sdk.close() (o sdk.close() en la síncrona) para no dejar conexiones abiertas. En JavaScript no hace falta cerrar nada.