# Los SDK de UTILIA OS

Qué cubren los SDK oficiales de JavaScript y Python, con qué credencial se autentica cada parte y por dónde empezar.

Con los SDK oficiales tu aplicación da de alta a sus usuarios, les abre tickets de soporte, les factura y les cobra, y tus copilotos trabajan con el CRM y Marketing, sin escribir las peticiones a mano. Hay dos: **`@utilia-os/sdk-js`** para JavaScript y TypeScript (Node.js 18 o superior) y **`utilia-sdk`** para Python (3.9 o superior, con versión asíncrona y síncrona). Los dos comparten numeración y métodos. La última publicada es la **4.1.0** en npm y la **4.2.0** en PyPI; lo que traen las versiones siguientes, que aún no se pueden instalar, y el historial están en [Versiones y compatibilidad](https://os.utilia.ai/docs/developers/sdk/versions).

Por encima de la API, los SDK añaden comprobaciones antes de enviar, reintentos con espera creciente, un identificador por petición para seguirla en los registros y un error único y estructurado, `UtiliaSDKError`. En esta sección, cada página explica un tema para los dos lenguajes, con el código en pestañas: elige tu lenguaje una vez y la documentación lo recordará.

## Qué puedes hacer

- **Usuarios**: identificar a las personas de tu aplicación, el primer paso de todo lo demás.
- **Soporte**: abrir tickets en su nombre, conversar con el equipo y seguir los cambios en tiempo real, con archivos adjuntos.
- **IA**: proponer el ticket a partir de texto, audio o capturas, y transcribir notas de voz.
- **Facturar y cobrar**: emitir facturas con numeración correlativa, enviarlas, entregar su enlace público, guardar tarjetas, cobrar con el usuario delante o sin él, programar cobros, devolver dinero y montar suscripciones con su autorización de cobro.
- **CRM**: contactos, leads y clientes por la API externa; oportunidades y el resto del CRM por MCP.
- **Marketing y otros servicios por MCP**: campañas, listas, entregabilidad, calendario laboral, buscador y avisos.
- **Avisos a tu servidor**: verificar la firma de los webhooks que te envía UTILIA OS, con el evento ya tipado.

## Qué credencial usa cada parte

**Qué credencial usa cada parte del SDK**

### Clave de la aplicación (API externa · /external/v1)

Casi todo el SDK. Va en la cabecera X-Api-Key, para integraciones de servidor a servidor. La clave nunca sale de tu servidor.

### OAuth de una persona (Carril MCP · sdk.mcp)

Para copilotos y herramientas que trabajan con los datos de quien las usa, con los permisos que esa persona acepta. No vale la clave de la aplicación.

### Ninguna (Avisos · sdk.webhooks)

La verificación de los avisos que recibes no hace red: solo necesita el secreto de firma.

Algunos servicios del SDK (contactos, presupuestos, calendario y ajustes de la organización) apuntan a rutas de la API del panel y hoy no son alcanzables desde el SDK con ninguna de las dos credenciales. El detalle, y qué usar en su lugar, está en la [Referencia de métodos](https://os.utilia.ai/docs/developers/sdk/reference#qué-credencial-alcanza-cada-servicio).

## Por dónde empezar

- [Instalar el SDK](https://os.utilia.ai/docs/developers/sdk/install): Requisitos, instalación y primera llamada en JavaScript y Python.
- [Configurar el cliente](https://os.utilia.ai/docs/developers/sdk/configuration): Tiempo de espera, reintentos, depuración y autenticación.
- [Usuarios externos](https://os.utilia.ai/docs/developers/sdk/users): Identifica a tus usuarios antes de abrirles tickets o facturarles.
- [Facturas](https://os.utilia.ai/docs/developers/sdk/invoices): Emite, envía, cobra y anula facturas desde tu aplicación.
- [Gestionar errores](https://os.utilia.ai/docs/developers/sdk/error-handling): Qué trae UtiliaSDKError y cuándo reintentar.
- [Referencia de métodos](https://os.utilia.ai/docs/developers/sdk/reference): Todos los servicios y métodos, con su nombre en cada lenguaje.