Consultar Historial de Servicios

Endpoint

POST /api/v2/queries/history

Descripción

Permite realizar consultas históricas avanzadas de servicios con múltiples filtros y criterios de búsqueda. Ideal para reportes, auditorías y análisis de datos operacionales.

Criterios de búsqueda:

• Por identificadores específicos (autorización, movimiento, placa)
• 📅 Por rangos de fechas con filtros adicionales
• 👤 Por creador o usuario específico
• 🔗 Combinación de múltiples filtros

Nota:

Se requiere al menos uno de los criterios oneOf para realizar la búsqueda.

Autenticación

Authorization: Basic <credentials>

Parámetros de Entrada

Body (JSON)

Campos Requeridos

Campo	Tipo	Descripción
line	string	Línea de negocio para filtrar los resultados

Criterios de Búsqueda (oneOf)

Campo	Tipo	Descripción
autNumber	string	Número de autorización específico
movNumber	string	Número de movimiento específico
licencePlate	string	Placa del vehículo
creator	string	Usuario creador del servicio
startDate + endDate	string	Rango de fechas (YYYY-MM-DD HH:MM)

Filtros Adicionales (opcionales)

Campo	Tipo	Descripción
businessNit	array	Lista de NITs de empresas
serviceStatus	array	Lista de estados de servicio
serviceType	array	Lista de tipos de servicio
closeStatus	array	Lista de estados de cierre
resourseId	array	Lista de IDs de recursos/técnicos
providerNit	array	Lista de NITs de prestadores

Ejemplos de Request

Búsqueda por Número de Autorización

{
  "line": "1",
  "autNumber": "TSV12345678"
}

Búsqueda por Rango de Fechas

{
  "line": "1",
  "startDate": "2025-07-01 00:00",
  "endDate": "2025-07-03 23:59"
}

Búsqueda con Filtros Múltiples

{
  "line": "LINE-COL01",
  "startDate": "2025-07-01 00:00",
  "endDate": "2025-07-01 23:59",
  "businessNit": ["901666", "556989"],
  "serviceStatus": ["Completado", "En proceso"],
  "serviceType": ["Grúa Liviana", "Ambulancia"],
  "providerNit": ["900123456"]
}

Respuestas

Éxito (200 Correcto)

{
  "status": true,
  "data": [
    {
      "idServicio": "TSV202507030001",
      "autNumber": "TSV12345678",
      "movNumber": "MOV001",
      "estado": "Completado",
      "fechaCreacion": "2025-07-03T10:30:00Z",
      "fechaCompletado": "2025-07-03T12:45:00Z",
      "prestador": {
        "nit": "900123456",
        "nombre": "Central Norte SAS"
      },
      "cliente": {
        "nombre": "Carlos Rodríguez",
        "telefono": "+57 300-123-4567"
      },
      "servicio": {
        "tipo": "Grúa Liviana",
        "descripcion": "Traslado de vehículo averiado",
        "origen": "Autopista Norte Km 15",
        "destino": "Taller Los Ángeles"
      },
      "facturacion": {
        "tarifa": "95000",
        "distancia": "12.5",
        "tiempo": "45"
      }
    }
  ]
}

Ejemplos de Código

cURL

# Por número de autorización
curl -X POST "[URL_API]/api/v2/queries/history" \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "line": "1",
    "autNumber": "TSV12345678"
  }'

# Por rango de fechas
curl -X POST "[URL_API]/api/v2/queries/history" \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "line": "1",
    "startDate": "2025-07-01 00:00",
    "endDate": "2025-07-03 23:59"
  }'

JavaScript

const consultarHistorial = async (criterios) => {
  const response = await fetch('[URL_API]/api/v2/queries/history', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${btoa('usuario:password')}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(criterios)
  });

  const result = await response.json();
  
  if (!result.status) {
    throw new Error(result.msg || 'Error en consulta');
  }
  
  return result.data;
};

// Ejemplos de uso
try {
  // Historial por autorización
  const porAutorizacion = await consultarHistorial({
    line: '1',
    autNumber: 'TSV12345678'
  });
  
  // Historial del día actual
  const hoy = new Date().toISOString().split('T')[0];
  const porFecha = await consultarHistorial({
    line: '1',
    startDate: `${hoy} 00:00`,
    endDate: `${hoy} 23:59`
  });
  
  // Historial con filtros
  const conFiltros = await consultarHistorial({
    line: 'LINE-COL01',
    startDate: '2025-07-01 00:00',
    endDate: '2025-07-01 23:59',
    serviceStatus: ['Completado'],
    serviceType: ['Grúa Liviana']
  });
  
  console.log('Registros encontrados:', conFiltros.length);
} catch (error) {
  console.error('Error:', error.message);
}

Python

import requests
from requests.auth import HTTPBasicAuth
from datetime import datetime, timedelta

def consultar_historial(criterios):
    response = requests.post(
        '[URL_API]/api/v2/queries/history',
        auth=HTTPBasicAuth('usuario', 'password'),
        json=criterios
    )
    
    result = response.json()
    
    if not result['status']:
        raise Exception(result.get('msg', 'Error en consulta'))
    
    return result['data']

# Ejemplos de uso
try:
    # Historial de los últimos 7 días
    fin = datetime.now()
    inicio = fin - timedelta(days=7)
    
    historial = consultar_historial({
        'line': '1',
        'startDate': inicio.strftime('%Y-%m-%d %H:%M'),
        'endDate': fin.strftime('%Y-%m-%d %H:%M'),
        'serviceStatus': ['Completado']
    })
    
    print(f"Servicios completados últimos 7 días: {len(historial)}")
    
    # Generar reporte
    for servicio in historial:
        print(f"ID: {servicio['idServicio']}")
        print(f"Estado: {servicio['estado']}")
        print(f"Prestador: {servicio['prestador']['nombre']}")
        print("---")
        
except Exception as e:
    print(f"Error: {e}")

Casos de Uso Comunes

Reportes Diarios

async function reporteDiario(fecha) {
  const servicios = await consultarHistorial({
    line: '1',
    startDate: `${fecha} 00:00`,
    endDate: `${fecha} 23:59`
  });
  
  const estadisticas = {
    total: servicios.length,
    completados: servicios.filter(s => s.estado === 'Completado').length,
    cancelados: servicios.filter(s => s.estado === 'Cancelado').length,
    ingresos: servicios
      .filter(s => s.facturacion)
      .reduce((sum, s) => sum + parseFloat(s.facturacion.tarifa || 0), 0)
  };
  
  return estadisticas;
}

Auditoría por Cliente

async function auditoriaPorCliente(telefonoCliente, dias = 30) {
  const fechaFin = new Date();
  const fechaInicio = new Date(fechaFin - dias * 24 * 60 * 60 * 1000);
  
  const servicios = await consultarHistorial({
    line: '1',
    startDate: fechaInicio.toISOString().replace('T', ' ').substr(0, 16),
    endDate: fechaFin.toISOString().replace('T', ' ').substr(0, 16)
  });
  
  return servicios.filter(s => 
    s.cliente && s.cliente.telefono === telefonoCliente
  );
}

📈 Análisis de Prestadores

async function analizarPrestadores(mes, año) {
  const servicios = await consultarHistorial({
    line: '1',
    startDate: `${año}-${mes.toString().padStart(2, '0')}-01 00:00`,
    endDate: `${año}-${mes.toString().padStart(2, '0')}-31 23:59`
  });
  
  const porPrestador = servicios.reduce((acc, servicio) => {
    const nit = servicio.prestador.nit;
    if (!acc[nit]) {
      acc[nit] = {
        nombre: servicio.prestador.nombre,
        servicios: 0,
        completados: 0,
        ingresos: 0
      };
    }
    
    acc[nit].servicios++;
    if (servicio.estado === 'Completado') {
      acc[nit].completados++;
      acc[nit].ingresos += parseFloat(servicio.facturacion?.tarifa || 0);
    }
    
    return acc;
  }, {});
  
  return Object.values(porPrestador);
}

Optimización de Consultas

Usar Filtros Específicos

// ❌ Consulta muy amplia
const todoElMes = await consultarHistorial({
  line: '1',
  startDate: '2025-07-01 00:00',
  endDate: '2025-07-31 23:59'
});

// ✅ Consulta optimizada
const soloCompletados = await consultarHistorial({
  line: '1',
  startDate: '2025-07-01 00:00',
  endDate: '2025-07-31 23:59',
  serviceStatus: ['Completado'],
  serviceType: ['Grúa Liviana']
});

Paginación Manual

async function consultarPorPeriodos(fechaInicio, fechaFin, diasPorConsulta = 7) {
  const resultados = [];
  let actual = new Date(fechaInicio);
  const fin = new Date(fechaFin);
  
  while (actual < fin) {
    const siguienteFecha = new Date(actual);
    siguienteFecha.setDate(actual.getDate() + diasPorConsulta);
    
    const servicios = await consultarHistorial({
      line: '1',
      startDate: actual.toISOString().replace('T', ' ').substr(0, 16),
      endDate: Math.min(siguienteFecha, fin).toISOString().replace('T', ' ').substr(0, 16)
    });
    
    resultados.push(...servicios);
    actual = siguienteFecha;
  }
  
  return resultados;
}

---

Rendimiento

Para consultas de grandes volúmenes de datos, usa filtros específicos y considera dividir el rango de fechas en períodos más pequeños.

Límites

Las consultas están limitadas a un máximo de 1000 registros por petición. Para obtener más resultados, divide la consulta en rangos de fechas más pequeños.