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

# Flujos comunes

> Recorridos recomendados para consumir Raul API en integraciones, billing, portal y backoffice

## Antes de empezar

Usa siempre la API productiva publicada en:

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

Si un modulo expone una ruta RESTful y una legacy, prefiere la RESTful.

## Flujo 1: autenticar y validar sesion

Usa este flujo al iniciar una integracion o antes de operar con endpoints protegidos.

1. Haz login con `POST /api/better-auth/sign-in/email`.
2. Guarda el token del header de respuesta `set-auth-token` como Bearer.
3. Consulta `GET /api/auth/users/me` para validar identidad y permisos.
4. La sesion se renueva sola mientras haya actividad (deslizante, sin endpoint de refresh).

```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"
  }'
```

## Flujo 2: crear un cliente y registrar direccion

Este flujo sirve para alta basica de cliente comercial.

1. Crea el cliente con `POST /api/v1/client`.
2. Si necesitas branding, sube logo con `POST /api/v1/client/{id}/logo`.
3. Agrega direccion con `POST /api/v1/clients/{clientId}/addresses`.
4. Consulta `GET /api/v1/clients/{clientId}/addresses` para verificar agrupacion por ciudad.

### Recomendaciones

* Usa `GET /api/v1/client/all/paginated` para backoffice o listados amplios.
* Trata varios campos de cliente como `snake_case`.

## Flujo 3: crear contacto y asociarlo al cliente

Usa este flujo cuando el cliente ya existe y necesitas registrar interlocutores.

1. Crea el contacto con `POST /api/v1/contact/create` o `POST /api/v1/contact/create-for-client`.
2. Si el contacto nace separado, asocialo con `POST /api/v1/contact/associate-to-client`.
3. Consulta roles funcionales con `GET /api/v1/contact/{contactId}/clients/{clientId}/functional-roles`.
4. Actualiza roles con `PUT /api/v1/contact/{contactId}/clients/{clientId}/functional-roles`.
5. Si detectas duplicados, revisa `GET /api/v1/contact/merge-preview` antes de `POST /api/v1/contact/merge`.

### Recomendaciones

* Usa `GET /api/v1/contact/by-client/{clientId}` para vistas por cliente.
* Usa `GET /api/v1/contact/all/paginated` cuando el volumen sea alto.

## Flujo 4: registrar un equipo GPS y asociarlo a suscripcion

Este flujo cubre el alta y consulta operativa de un GPS.

1. Revisa catalogos necesarios: modelos, marcas, categorias, plataformas y estados.
2. Crea el equipo con `POST /api/v1/gps_details/create`.
3. Consulta el detalle por `GET /api/v1/gps_details/{gps_details_id}`.
4. Usa `GET /api/v1/gps_details/related-data/{gps_details_id}` para contexto ampliado.
5. Consulta planes con `GET /api/v1/subscription_plan/all`.
6. Crea la suscripcion con `POST /api/v1/subscription_details/create`.
7. Revisa estado y resumen con `GET /api/v1/subscription_details/get/{subscription_detail_id}` y `GET /api/v1/subscription_details/summary`.

### Recomendaciones

* Para lotes grandes, prefiere `GET /api/v1/gps_details/all/cursor`.
* Usa `POST /api/v1/subscription_details/transfer` solo cuando realmente cambie titularidad.

## Flujo 5: ejecutar una visita tecnica con evidencia

Este flujo aplica cuando ya existe la visita o se necesita crear y documentar una visita tecnica.

1. Crea la visita con `POST /api/v1/visit_detail`.
2. Consulta la agenda o resumen con `GET /api/v1/visit_detail/paginated` o `GET /api/v1/visit_detail/summary`.
3. Si necesitas evidencia, sube archivos con `POST /api/v1/visit_detail/upload/{visitDetailId}`.
4. Recupera imagenes con `GET /api/v1/visit_detail/images/{visitDetailId}`.
5. Si necesitas respaldo formal, descarga `GET /api/v1/visit_detail/{id}/pdf`.

### Recomendaciones

* Antes de reintentar un upload, verifica si la imagen ya quedo registrada.
* Para vistas por tecnico, usa `GET /api/v1/visit_detail/by-technicians`.

## Flujo 6: ciclo de invoice moderna y DTE

Este es uno de los flujos mas sensibles del sistema y varias mutaciones requieren perfil admin explicito.

1. Lista o crea facturas con `GET|POST /api/v1/billing/invoices`; la creación deja un borrador (`DRAFT`).
2. Publica con `POST /api/v1/billing/invoices/{id}/publish`. Esta operación intenta emitir el DTE automáticamente.
3. Consulta `GET /api/v1/billing/invoices/{id}` y el DTE asociado antes de decidir si hay que reintentar. `PUBLISHED` indica que la publicación se guardó, pero la emisión no terminó; `DTE_SENT` indica envío con TrackID, no aceptación del SII.
4. Si la emisión no llegó a iniciarse, usa `POST /api/v1/billing/invoices/{id}/emit-dte` para retomar. Si el DTE está en `SII_UPLOAD_UNCERTAIN`, concilia el folio con el SII antes de cualquier nueva emisión.
5. Para actualizar el veredicto de un DTE con TrackID, usa `POST /api/v1/dte/documents/{dteId}/sync`.
6. Previsualiza y envía correo con `POST /api/v1/billing/invoices/{id}/email-preview` y `POST /api/v1/billing/invoices/{id}/send-email` cuando corresponda.
7. Registra pago con `POST /api/v1/billing/invoices/{id}/register-payment`.

### Recomendaciones

* Verifica el estado comercial y el tributario antes de repetir mutaciones; una respuesta de publicación no prueba aceptación del SII.
* Usa `POST /api/v1/billing/invoices/batch/generate-monthly` solo para procesos batch.
* Estas rutas requieren sesión de backoffice, rol `admin` y acceso al módulo Finanzas.
* Consulta la [guía de facturas y DTE](/invoices-guide) para payloads, estados y recuperación.

## Flujo 7: acceso y autoservicio del portal cliente

1. Solicita magic link con `POST /api/portal/auth/request`.
2. Intercambia el token con `POST /api/portal/auth/exchange`.
3. Lista documentos con `GET /api/portal/invoices`.
4. Descarga detalle o respaldos con `GET /api/portal/invoices/{id}`, `/pdf`, `/xml` o `/detail-xlsx`.
5. Si el cliente pagara o notificara transferencia, usa `POST /api/portal/invoices/pay`, `POST /api/portal/invoices/{id}/pay` o `POST /api/portal/invoices/{id}/notify-transfer`.
6. Si el flujo es de soporte, usa `GET /api/portal/support/tickets` y `POST /api/portal/support/tickets/{ticketId}/comments`.

### Recomendaciones

* En portal, el acceso depende de roles funcionales del contacto.
* `invoices` y `support` no comparten exactamente la misma matriz de acceso.

## Flujo 8: inbox omnichannel con shared mailbox

1. Consulta inbox y threads con `GET /api/omnichannel/inbox` y `GET /api/omnichannel/threads/{threadId}`.
2. Si trabajas con bandejas compartidas, lista `GET /api/shared-mailboxes` y las del usuario con `GET /api/shared-mailboxes/my-mailboxes`.
3. Si eres admin, registra o sincroniza mailboxes con `POST /api/shared-mailboxes`, `POST /api/shared-mailboxes/bootstrap` y `POST /api/shared-mailboxes/{id}/sync`.
4. Responde por email/WhatsApp con `POST /api/omnichannel/threads/{threadId}/reply`, `POST /api/omnichannel/send-shared` o `POST /api/omnichannel/send-whatsapp`.
5. Ordena la operacion con assignment, tags y estado de lectura.

### Recomendaciones

* Evita retries ciegos sobre envio real de mensajes.
* Reconsulta thread y ownership antes de reenviar o reasignar.

## Manejo de rutas legacy

Si encuentras dos endpoints con el mismo objetivo:

* Prefiere rutas sin verbos como `get`, `create`, `update` o `delete`.
* Prefiere recursos por ID con `/{id}` frente a `/get/{id}`.
* Deja la ruta legacy solo para compatibilidad con consumidores existentes.

## Enlaces relacionados

* [Autenticacion](/authentication)
* [Permisos y roles](/authorization-and-roles)
* [Introduccion API](/api-reference/introduction)
* [Guia para IA](/ai-consumption)
* [OpenAPI JSON](https://api.raul.ugps.io/api/openapi.json)


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