Flujos comunes

​

Antes de empezar

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

​

Flujo 1: autenticar y validar sesion

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

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

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

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

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

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

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

• 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
• Permisos y roles
• Introduccion API
• Guia para IA
• OpenAPI JSON