> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raul.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/auth/login`
2. Guardar `token` como Bearer JWT
3. Renovar con `POST /api/auth/refresh` cuando expire el access token
4. Cerrar sesion con `POST /api/auth/logout` si necesitas invalidar refresh tokens

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

## Preferencias por modulo

### Auth

* Usa `username` como email en login.
* No infieras usuarios desde tokens vencidos; renueva con `refresh`.
* 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)