Technical Routes - GB App - Power BI Report Manager

Technical Routes Overview

Manage technical service routes for field technicians, including visit scheduling, client information, and route status tracking.

List Technical Routes

Retrieve technical routes accessible to the authenticated user.

GET /rutas-tecnicas

Authentication & Permissions

Authorization

string

required

Valid session or Sanctum token

Requires:

rutas-tecnicas.ver permission

Authorization Behavior

Regular Users:

See only routes where they are the vendor (CodVendedor)
See routes of shared technical users

Supervisors/Admins:

Users with rutas-tecnicas.ver-todos permission
Roles: super-admin, AsistenteVentas, Gerencia, supervisor
Can see all routes in the system

Query Parameters

fecha_inicio

date

Filter routes starting from this date

fecha_fin

date

Filter routes ending on or before this date

Response

Returns Inertia view with:

rutas

array

Array of route objects grouped by NumeroRuta

filtros

object

Applied filters

permisos

object

User permissions for routes

Route Object Structure

NumeroRuta

string

Unique route identifier

FechaInicio

string

Route start date (formatted: YYYY-MM-DD Day)

FechaFin

string

Route end date (formatted: YYYY-MM-DD Day)

CodVendedor

string

Vendor/sales representative code

cerrada

boolean

Whether route is closed

totalVisitas

integer

Total number of visits in route

visitas

array

Array of visit objects

Get Route Details

Retrieve detailed information about a specific route.

GET /rutas-tecnicas/{numeroRuta}

Path Parameters

numeroRuta

string

required

Route number

Response

Returns Inertia view with:

ruta

object

Route details with all visits

Visit Object Structure

idVisita

integer

Visit ID

NumeroRuta

string

Route number

Nit

string

Client NIT/document

NombreCliente

string

Client name

DireccionCompleta

string

Complete client address

FechaVisita

string

Scheduled visit date (YYYY-MM-DD Day)

NomContacto

string

Contact person name

TelContacto

string

Contact phone number

CodVendedor

string

Vendor code

CodTecnico

string

Technician code

Observaciones

string

Visit observations

Create Technical Route

Create a new technical route with visits.

POST /rutas-tecnicas

Permissions

Requires:

rutas-tecnicas.crear permission

Request Body

fecha_inicio

date

required

Route start date

fecha_fin

date

required

Route end date (must be >= fecha_inicio)

visitas

array

required

Array of visit objects

Visit Object

visitas[].nit

string

required

Client NIT (max 50 chars)

visitas[].nombre_cliente

string

required

Client name (max 200 chars)

visitas[].direccion_completa

string

required

Complete address (max 500 chars)

visitas[].fecha_visita

date

required

Visit date (must be within route date range)

visitas[].cod_tecnico

string

required

Technician code (max 50 chars)

visitas[].nom_contacto

string

Contact name (max 200 chars)

visitas[].tel_contacto

string

Contact phone (max 50 chars)

visitas[].observaciones

string

Visit observations (max 500 chars)

Example Request

curl -X POST https://your-domain.com/rutas-tecnicas \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fecha_inicio": "2026-03-10",
    "fecha_fin": "2026-03-14",
    "visitas": [
      {
        "nit": "900123456",
        "nombre_cliente": "Empresa ABC S.A.",
        "direccion_completa": "Calle 123 #45-67, Bogotá",
        "fecha_visita": "2026-03-10",
        "cod_tecnico": "TEC001",
        "nom_contacto": "Juan Pérez",
        "tel_contacto": "3001234567",
        "observaciones": "Mantenimiento preventivo"
      },
      {
        "nit": "900654321",
        "nombre_cliente": "Industrias XYZ Ltda",
        "direccion_completa": "Carrera 98 #76-54, Medellín",
        "fecha_visita": "2026-03-11",
        "cod_tecnico": "TEC001",
        "nom_contacto": "María García",
        "tel_contacto": "3009876543",
        "observaciones": "Instalación nuevo equipo"
      }
    ]
  }'

Response

Redirects to create page with success message:

Ruta técnica #{numeroRuta} creada exitosamente con {count} visita(s)

Route Merging Behavior

If an open route exists with overlapping dates:

User is redirected to edit the existing route
Routes are shared among advisors and their technical users

Update Technical Route

Update an existing technical route.

PUT /rutas-tecnicas/{numeroRuta}

Permissions

Requires:

rutas-tecnicas.editar permission
OR ownership of the route

Path Parameters

numeroRuta

string

required

Route number to update

Request Body

Same structure as create, plus:

visitas[].idVisita

integer

Existing visit ID (omit for new visits)

Ownership Rules

Users can only modify their own visits
Supervisors can modify all visits
Deleting visits: only owner or supervisor

Example Request

curl -X PUT https://your-domain.com/rutas-tecnicas/RT-2026-001 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fecha_inicio": "2026-03-10",
    "fecha_fin": "2026-03-14",
    "visitas": [
      {
        "idVisita": 123,
        "nit": "900123456",
        "nombre_cliente": "Empresa ABC S.A.",
        "direccion_completa": "Calle 123 #45-67, Bogotá",
        "fecha_visita": "2026-03-10",
        "cod_tecnico": "TEC001",
        "nom_contacto": "Juan Pérez Updated",
        "tel_contacto": "3001234567"
      }
    ]
  }'

Response

Redirects to route show page with success message.

Client Search API

Search for clients to add to routes.

GET /rutas-tecnicas/api/clientes/buscar

Query Parameters

string

required

Search term (min 2 characters)

Response

clients

array

Array of matching clients (max 10)

ClienteId

string

Client ID

Nit

string

Client NIT

NombreCliente

string

Client name

CodAsesor

string

Advisor code

NombreAsesor

string

Advisor name

Zona

string

Client zone

Example Request

curl -X GET "https://your-domain.com/rutas-tecnicas/api/clientes/buscar?q=ABC" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Get Client Addresses

Retrieve all addresses for a specific client.

GET /rutas-tecnicas/api/clientes/{clienteId}/direcciones

Path Parameters

clienteId

string

required

Client NIT/ID

Response

addresses

array

Array of client addresses

Address Object

DireccionId

string

Address ID (NIT-Sede format)

NitCliente

string

Client NIT

Sede

string

Branch/location code

DireccionCompleta

string

Complete address with complement

Ciudad

string

City

Departamento

string

Department/state

NombreContacto

string

Contact person name

Get Recommended Contact Data

Get contact suggestions based on previous visits to this address.

GET /rutas-tecnicas/api/clientes/{clienteId}/contacto-recomendado

Query Parameters

direccion

string

required

Address to search for

Response

sugerencias

array

Array of suggested contacts (max 10)

nomContacto

string

Contact name

telContacto

string

Contact phone

fechaVisita

date

Date of previous visit

label

string

Formatted label for display

Implementation Notes

Source: app/Http/Controllers/RutaTecnicaController.php

Route Auto-Close

Routes are automatically closed on Friday after 2:00 PM via RutaTecnica::cerrarRutasVencidas().

Route Number Generation

Route numbers are generated using RutaTecnica::generarNumeroRuta().

Data Sources

Client data is retrieved from SQL Server database connection sqlsrv:

Clients: V_360_tec_clientes view
Addresses: V_360_tec_clientes_sedes view

Date Formatting

Dates are formatted with Spanish day names:

Format: YYYY-MM-DD Day
Example: 2026-03-10 Lun

Source: RutaTecnicaController.php:26-44

Authentication

Reports

Users & Roles

Business APIs

​Technical Routes Overview

​List Technical Routes

​Authentication & Permissions

​Authorization Behavior

​Query Parameters

​Response

​Route Object Structure

​Get Route Details

​Path Parameters

​Response

​Visit Object Structure

​Create Technical Route

​Permissions

​Request Body

​Visit Object

​Example Request

​Response

​Route Merging Behavior

​Update Technical Route

​Permissions

​Path Parameters

​Request Body

​Ownership Rules

​Example Request

​Response

​Client Search API

​Query Parameters

​Response

​Example Request

​Get Client Addresses

​Path Parameters

​Response

​Address Object

​Get Recommended Contact Data

​Query Parameters

​Response

​Implementation Notes

​Route Auto-Close

​Route Number Generation

​Data Sources

​Date Formatting

Build docs developers (and LLMs) love

Technical Routes Overview

List Technical Routes

Authentication & Permissions

Authorization Behavior

Query Parameters

Response

Route Object Structure

Get Route Details

Path Parameters

Response

Visit Object Structure

Create Technical Route

Permissions

Request Body

Visit Object

Example Request

Response

Route Merging Behavior

Update Technical Route

Permissions

Path Parameters

Request Body

Ownership Rules

Example Request

Response

Client Search API

Query Parameters

Response

Example Request

Get Client Addresses

Path Parameters

Response

Address Object

Get Recommended Contact Data

Query Parameters

Response

Implementation Notes

Route Auto-Close

Route Number Generation

Data Sources

Date Formatting