Para IA

​

Fuente de verdad

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

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

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.

claude mcp add --transport http raul https://mcp-raul.ugps.io/mcp

{
  "mcpServers": {
    "raul": {
      "type": "http",
      "url": "https://mcp-raul.ugps.io/mcp"
    }
  }
}

​

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

• 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

• 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
• OpenAPI JSON
• Health check