> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ugps.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Para IA

> Guia de consumo de Raul API para agentes, asistentes y automatizaciones

## Fuente de verdad

Si eres una IA o un integrador automatico, usa estas fuentes en este orden:

1. `https://api.raul.ugps.io/api/openapi.json`
2. La pestaña **API** generada por Mintlify
3. Esta guia para criterios de uso y preferencias operativas

## Reglas de consumo

* Prefiere siempre rutas RESTful cuando exista una alternativa equivalente.
* Si encuentras una ruta marcada como `legacy`, usala solo por compatibilidad.
* Interpreta autenticacion desde `security`, DTOs y respuestas tipadas.
* No asumas que `api.ugps.io` y `api.raul.ugps.io` son equivalentes.
* La base operativa correcta para esta documentacion es `https://api.raul.ugps.io`.

## Flujo minimo de autenticacion

1. `POST /api/better-auth/sign-in/email`
2. Guardar el token del header de respuesta `set-auth-token` como Bearer
3. La sesion es deslizante (30 dias, sin refresh); no expira mientras haya actividad
4. Cerrar sesion con `POST /api/better-auth/sign-out` si necesitas invalidarla

```bash theme={null}
curl -i -X POST "https://api.raul.ugps.io/api/better-auth/sign-in/email" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@ugps.cl",
    "password": "password123"
  }'
```

## Servidor MCP

Raul expone un servidor MCP (Model Context Protocol) con sus operaciones como
herramientas para agentes (Claude Code, Claude Desktop, claude.ai y cualquier
cliente MCP con transporte Streamable HTTP). Es un servicio propio (su propio
host, su propio App Service, sin proxy de la API por delante) que sirve su
propio descubrimiento OAuth:

```
https://mcp-raul.ugps.io/mcp
```

* **Login por persona**: Better Auth, dentro de la API de Raul, es el
  authorization server OAuth 2.1 de este MCP (plugin `@better-auth/mcp`). Al
  conectar, el cliente descubre el authorization server vía
  `/.well-known/oauth-protected-resource` (en el mismo host del MCP) y cada
  usuario completa el login con su propia cuenta de Raul. No se comparten
  credenciales ni tokens: las herramientas corren con los permisos de quien
  se autenticó (por ejemplo, `raul_get_business_dashboard` responde 403 si no
  es admin).
* **Token**: el token de acceso es un JWT emitido por Better Auth con scope
  `raul:api`, vida de 1 hora y refresh de 30 días. El MCP lo verifica
  localmente contra el JWKS del issuer (sin llamar a la API en cada
  request) y lo reenvía tal cual como bearer a la API — la API acepta ese
  mismo JWT en su `SessionAuthGuard`, así que no hay una segunda sesión ni
  traducción de credenciales de por medio.
* **Herramientas** (`raul_*`): 15 herramientas curadas — clientes, contactos,
  pipelines y oportunidades, cotizaciones (crear y generar PDF), bandeja
  omnicanal (correo y WhatsApp), tickets — más dos genéricas,
  `raul_find_endpoint` y `raul_call`, que buscan y llaman cualquier endpoint
  del OpenAPI (793 endpoints) cuando no hay una herramienta curada para eso;
  las llamadas que escriben datos exigen `confirm: true`. Fuera de alcance a
  propósito: el dominio de finanzas.

Conexión desde Claude Code:

```bash theme={null}
claude mcp add --transport http raul https://mcp-raul.ugps.io/mcp
```

Configuración equivalente para `.mcp.json` o un conector de Claude Desktop / claude.ai:

```json theme={null}
{
  "mcpServers": {
    "raul": {
      "type": "http",
      "url": "https://mcp-raul.ugps.io/mcp"
    }
  }
}
```

El código vive en `apps/raul-mcp-server` del monorepo; la lista completa de herramientas y
sus endpoints está en su `README.md`.

## Preferencias por modulo

### Auth

* Usa `email` en el login (no `username`).
* No hay endpoint de refresh: si el token deja de servir, vuelve a hacer sign-in.
* Soporta gestion de usuarios, toggle de estado activo, avatar y reset de password.

### Clients

* Muchas respuestas de clientes usan `snake_case` por compatibilidad con frontend legacy.
* Para filtros amplios o listados grandes, prefiere endpoints paginados (`/all/paginated`).
* Soporta upload de logo por cliente.

### Client Father

* Representa clientes padre que agrupan clientes hijos.
* Disponible con paginacion y con vista de suscripciones asociadas.

### Client Addresses

* Las direcciones se agrupan por ciudad al consultarlas.
* CRUD disponible bajo `/clients/{clientId}/addresses` y `/client-addresses/{id}`.

### Contact

* Soporta paginacion, agrupacion por empresa, leads y busqueda por cliente.
* Permite merge de contactos duplicados (preview + merge).
* Functional roles se asignan por relacion contacto-cliente.
* Soporta upload y borrado de foto de contacto.

### Vehicle / Asset

* `/vehicle` y `/asset` son alias equivalentes para algunos endpoints.
* Soporta filtros y listado de nombres.
* Incluye catalogo de tipos de vehiculo (`/type_vehicle/all`).

### Activities

* Timeline de actividades por cliente, contacto o visita.
* Soporta archivos adjuntos (upload y download).
* Tipos de actividad son configurables via CRUD.

### GPS Details

* Modulo principal de equipos GPS.
* Muchos endpoints tienen alias: `/gps_details/...` y `/gps/...` son equivalentes.
* Si necesitas listar grandes volumenes, prefiere cursor pagination (`/all/cursor`) sobre offset pagination.
* Si una ruta existe como `get/:id` y como `/:id`, prefiere la RESTful.
* Incluye conteo (`/count`), resumen (`/summary`) y datos relacionados (`/related-data`).

### GPS (sub-modulos)

* **GPS Models**: CRUD de modelos, soporta upload de ficha tecnica PDF.
* **GPS Platforms**: CRUD de plataformas GPS.
* **GPS Inventory**: Estados de inventario, incluye vista para visitas (`/get_x_visit`).
* **GPS Brands**: CRUD de marcas GPS.
* **GPS Categories**: CRUD de categorias GPS.
* **GPS Status**: Solo lectura, lista todos los estados.
* **GPS History**: Historial de un equipo GPS por ID.

### Subscription Details

* CRUD de suscripciones con paginacion offset y cursor.
* Soporta resumen (`/summary`), razones de cancelacion, y reversion de cancelacion.
* Permite asignar suscripcion a cliente hijo y transferir entre clientes.
* Consulta por cliente con `/client/{client_id}`.

### Subscription Plan

* CRUD de planes de suscripcion.

### Subscription Status / Currency

* Status: solo lectura, lista todos los estados de suscripcion.
* Currency: CRUD completo de monedas.

### Catalogos auxiliares

* **Rubro**: Sectores de negocio (solo lectura).
* **City**: Ciudades con provincia y region (solo lectura).
* **Type of Contract**: CRUD de tipos de contrato.
* **Cargo / RoleContact**: CRUD de cargos y tipos de contacto.
* **Communication**: CRUD de tipos de comunicacion.
* **PlataformClient**: Actualizacion de IDs de cliente temporales.

## Rutas legacy y duplicadas

Algunos modulos mantienen rutas legacy por compatibilidad. Cuando encuentres dos rutas con el mismo objetivo:

* Prefiere la que diga `RESTful`
* Prefiere la que no incluya verbos en el path (`get`, `create`, `update`, `delete`)
* Usa la legacy solo si el consumidor actual depende de ella

## Criterio de interpretacion

Si una operacion tiene descripcion breve:

* usa `summary` para intencion
* usa `description` para restricciones y preferencia de uso
* usa request/response DTOs para forma exacta de datos
* usa `ApiResponse` y codigos HTTP para manejo de errores

## Enlaces utiles

* [Introduccion API](/api-reference/introduction)
* [OpenAPI JSON](https://api.raul.ugps.io/api/openapi.json)
* [Health check](https://api.raul.ugps.io/api/health)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.