Skip to main content

​
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
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