> ## 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.

# Introduccion

> Como esta organizada Raul API y por donde conviene empezar a integrarla

## Endpoint base

La API productiva disponible para consumo esta en:

* **Base URL**: `https://api.raul.ugps.io`
* **Health check**: `https://api.raul.ugps.io/api/health`
* **OpenAPI JSON**: `https://api.raul.ugps.io/api/openapi.json`

## Como leer esta documentacion

Raul combina dos capas:

* **Guia**: explica dominios, flujos, decisiones de integracion y contexto de negocio
* **API**: muestra el contrato exacto generado desde OpenAPI

Regla simple:

* si buscas un endpoint puntual, entra a **API**
* si buscas entender que modulo o secuencia usar, empieza por **Guia**

## Autenticacion

La API interna usa autenticacion `Bearer` con JWT. El portal cliente usa un flujo separado de magic link y token portal.

Para detalles:

* [Autenticacion](/authentication)
* [Permisos y roles](/authorization-and-roles)

## Grupos funcionales actuales

| Grupo Mintlify | Que cubre |
| - | - |
| **Acceso** | login, refresh, logout, usuarios y recuperacion |
| **Clientes** | clientes, clientes padre, direcciones, contactos y vehiculos |
| **Operaciones** | GPS, suscripciones, actividades, visitas, tecnicos, transfers y tareas |
| **Comunicaciones** | omnichannel, inbox, shared mailboxes, tags, spam y email sync |
| **Ventas** | quotes, pipeline, outreach, equipment sales, shipment orders y catalogos comerciales |
| **Finanzas** | invoices modernas, billing legacy, DTE, cuentas por pagar y pagos |
| **Diagnostico** | health, consumo, Emnify, Atlas, Flespi, chips y troubleshooting |
| **Configuraciones** | catalogos maestros, tipos, lifecycles y parametros base |
| **Plataforma** | portal cliente, templates, RRHH, notificaciones, AI support y teams bot |

## Reglas practicas de integracion

* Prefiere rutas RESTful cuando exista una alternativa legacy equivalente.
* En modulos con gran volumen de datos, prefiere paginacion o cursor.
* Algunos recursos tienen alias legacy y modernos; confirma la opcion recomendada en la pestaña **API**.
* No asumas que toda ruta autenticada es `admin-only`: revisa [Permisos y roles](/authorization-and-roles).
* Para agentes o automatizaciones, combina esta pagina con [Guia para IA](/ai-consumption).

## Punto de partida recomendado

Si estas integrando desde cero:

1. autentica con `/api/better-auth/sign-in/email`
2. valida la sesion con `/api/auth/users/me`
3. identifica el dominio funcional correcto en Mintlify
4. consume el endpoint exacto desde la pestaña **API**

## Enlaces rapidos

<Card title="Abrir JSON OpenAPI" icon="file-json" href="https://api.raul.ugps.io/api/openapi.json">
  Ver definicion completa de endpoints y schemas
</Card>

<Card title="Ver health check" icon="heartbeat" href="https://api.raul.ugps.io/api/health">
  Confirmar disponibilidad operativa del backend
</Card>

<Card title="Permisos y roles" icon="shield-check" href="/authorization-and-roles">
  Revisar JWT global, RBAC admin y roles funcionales del portal
</Card>


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