Opciones de historial

El endpoint GET /api/v2/queries/history-options permite obtener las opciones disponibles para filtrar el historial de operaciones en la API de TSALVA.

URL del Endpoint

GET [URL_API]/api/v2/queries/history-options

Autenticación

Este endpoint requiere autenticación básica HTTP. Consulta la guía de autenticación para más detalles.

Parámetros

Parámetros de URL (Query Parameters)

Parámetro	Tipo	Requerido	Descripción
q	string	No	Filtro específico para obtener solo ciertas opciones

Valores permitidos para q:

• task_status - Estados de tareas
• service_status - Estados de servicios
• service_close_status - Estados de cierre
• business_nit - NITs de empresas
• service_type - Tipos de servicio
• resource_id - IDs de recursos
• provider_nit - NITs de proveedores
• line - Líneas de negocio

Nota: Si no se envía el parámetro q, se retornan todas las opciones disponibles.

Respuesta exitosa

Código de estado: 200 Correcto

Estructura de la respuesta

{
  "status": true,
  "data": {
    "taskStatus": [
      {
        "id": 1,
        "name": "Pendiente"
      },
      {
        "id": 2,
        "name": "En proceso"
      },
      {
        "id": 3,
        "name": "Completado"
      }
    ],
    "serviceStatus": [
      {
        "id": 1,
        "name": "Activo"
      },
      {
        "id": 2,
        "name": "En proceso"
      },
      {
        "id": 3,
        "name": "Finalizado"
      }
    ],
    "serviceCloseStatus": [
      {
        "id": 0,
        "name": "Abierto"
      },
      {
        "id": 1,
        "name": "Cerrado"
      }
    ],
    "businessNits": [
      {
        "nit": "123456789",
        "name": "Aseguradora XYZ"
      },
      {
        "nit": "987654321",
        "name": "Seguros ABC"
      }
    ],
    "serviceTypes": [
      {
        "id": 1,
        "name": "Grúa Liviana",
        "lineId": 1
      },
      {
        "id": 2,
        "name": "Grúa Pesada",
        "lineId": 1
      }
    ],
    "resourceIds": [
      {
        "id": "TECH001",
        "name": "Carlos Rodríguez",
        "type": "own"
      },
      {
        "id": "TECH002",
        "name": "María González",
        "type": "own"
      }
    ],
    "providerNits": [
      {
        "nit": "PROV001",
        "name": "Proveedor Externo SA"
      }
    ],
    "lines": [
      {
        "id": 1,
        "name": "Grúas"
      },
      {
        "id": 2,
        "name": "Mecánica"
      }
    ]
  },
  "msg": "Opciones de historial obtenidas correctamente"
}

Respuestas filtradas

Cuando se utiliza el parámetro q, la respuesta solo incluye el tipo de opción solicitado:

Ejemplo: ?q=task_status

{
  "status": true,
  "data": {
    "taskStatus": [
      {
        "id": 1,
        "name": "Pendiente"
      },
      {
        "id": 2,
        "name": "En Proceso"
      },
      {
        "id": 3,
        "name": "Completado"
      }
    ]
  },
  "msg": "Opciones de historial obtenidas correctamente"
}

Ejemplo: ?q=service_type

{
  "status": true,
  "data": {
    "serviceTypes": [
      {
        "id": 1,
        "name": "Grúa Liviana",
        "lineId": 1
      },
      {
        "id": 2,
        "name": "Grúa Pesada",
        "lineId": 1
      }
    ]
  },
  "msg": "Opciones de historial obtenidas correctamente"
}

Ejemplo: ?q=business_nit

{
  "status": true,
  "data": {
    "businessNits": [
      {
        "nit": "123456789",
        "name": "Aseguradora XYZ"
      },
      {
        "nit": "987654321",
        "name": "Seguros ABC"
      }
    ]
  },
  "msg": "Opciones de historial obtenidas correctamente"
}

Campos de la respuesta

Estados de tarea (taskStatus)

• id: Identificador único del estado de tarea
• name: Nombre descriptivo del estado

Estados de dervicio (serviceStatus)

• id: Identificador único del estado del servicio
• name: Nombre descriptivo del estado del servicio

Estados de cierre (serviceCloseStatus)

• id: Identificador del estado de cierre (0 = Abierto, 1 = Cerrado)
• name: Nombre descriptivo del estado

NITs de empresas (businessNits)

• nit: Número de identificación tributaria de la empresa
• name: Nombre de la empresa o aseguradora

Tipos de servicio (serviceTypes)

• id: Identificador único del tipo de servicio
• name: Nombre del tipo de servicio
• lineId: Identificador de la línea de negocio a la que pertenece

IDs de recursos (resourceIds)

• id: Identificador único del recurso (técnico/conductor)
• name: Nombre completo del recurso
• type: Tipo de recurso ("own" = propio, "external" = externo)

NITs de proveedores (providerNits)

• nit: Número de identificación del proveedor
• name: Nombre del proveedor

Líneas de negocio (lines)

• id: Identificador único de la línea de negocio
• name: Nombre de la línea de negocio

Ejemplos de uso

cURL

Obtener todas las opciones:

curl -X GET \
  [URL_API]/api/v2/queries/history-options \
  -H "Authorization: Basic $(echo -n 'tu_usuario:tu_password' | base64)"

Obtener solo estados de tarea:

curl -X GET \
  "[URL_API]/api/v2/queries/history-options?q=task_status" \
  -H "Authorization: Basic $(echo -n 'tu_usuario:tu_password' | base64)"

Obtener solo tipos de servicio:

curl -X GET \
  "[URL_API]/api/v2/queries/history-options?q=service_type" \
  -H "Authorization: Basic $(echo -n 'tu_usuario:tu_password' | base64)"

JavaScript

Función genérica para obtener opciones:

const username = 'tu_usuario';
const password = 'tu_password';
const credentials = btoa(`${username}:${password}`);

async function getHistoryOptions(filter = null) {
  const url = filter 
    ? `[URL_API]/api/v2/queries/history-options?q=${filter}`
    : '[URL_API]/api/v2/queries/history-options';
    
  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'Authorization': `Basic ${credentials}`,
      'Content-Type': 'application/json'
    }
  });
  
  return await response.json();
}

// Ejemplos de uso:
try {
  // Obtener todas las opciones
  const todasLasOpciones = await getHistoryOptions();
  
  // Obtener solo estados de servicio
  const estadosServicio = await getHistoryOptions('service_status');
  
  // Obtener solo empresas
  const empresas = await getHistoryOptions('business_nit');
  
  console.log('Todas las opciones:', todasLasOpciones);
  console.log('Estados de servicio:', estadosServicio);
  console.log('Empresas:', empresas);
  
} catch (error) {
  console.error('Error:', error);
}

Python

Función para obtener opciones con filtro:

import requests
import base64

def get_history_options(username, password, filter_type=None):
    credentials = base64.b64encode(f'{username}:{password}'.encode()).decode()
    
    url = '[URL_API]/api/v2/queries/history-options'
    if filter_type:
        url += f'?q={filter_type}'
    
    response = requests.get(
        url,
        headers={
            'Authorization': f'Basic {credentials}',
            'Content-Type': 'application/json'
        }
    )
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"Error: {response.status_code}")

# Ejemplos de uso:
username = 'tu_usuario'
password = 'tu_password'

try:
    # Obtener todas las opciones
    todas_opciones = get_history_options(username, password)
    
    # Obtener solo estados de tarea
    estados_tarea = get_history_options(username, password, 'task_status')
    
    # Obtener solo tipos de servicio
    tipos_servicio = get_history_options(username, password, 'service_type')
    
    print("Todas las opciones:", todas_opciones)
    print("Estados de tarea:", estados_tarea)
    
except Exception as e:
    print(f"Error: {e}")
import requests
import base64

username = 'tu_usuario'
password = 'tu_password'
credentials = base64.b64encode(f'{username}:{password}'.encode()).decode()

response = requests.get(
    '[URL_API]/api/v2/queries/history-options',
    headers={
        'Authorization': f'Basic {credentials}',
        'Content-Type': 'application/json'
    }
)

if response.status_code == 200:
    data = response.json()
    options = data['data']
    
    print("Estados de tarea disponibles:")
    for status in options['taskStatus']:
        print(f"- {status['name']} (ID: {status['id']})")
    
    print("\nTipos de servicio:")
    for service in options['serviceTypes']:
        print(f"- {service['name']} (ID: {service['id']}, Línea: {service['lineId']})")
    
    print("\nEmpresas:")
    for business in options['businessNits']:
        print(f"- {business['name']} (NIT: {business['nit']})")
else:
    print(f"Error: {response.status_code}")
    print(response.json())

Casos de uso

2. Construcción de filtros dinámicos completos

// Obtener todas las opciones para construir filtros completos
// Usar cuando necesites múltiples tipos de filtros en la misma interfaz
async function buildCompleteHistoryFilters() {
  const options = await getHistoryOptions(); // Sin parámetro q para obtener todo
  
  const filters = {
    taskStatus: options.data.taskStatus.map(status => ({
      value: status.id,
      label: status.name
    })),
    serviceStatus: options.data.serviceStatus.map(status => ({
      value: status.id,
      label: status.name
    })),
    serviceTypes: options.data.serviceTypes.map(type => ({
      value: type.id,
      label: type.name,
      lineId: type.lineId
    })),
    businessNits: options.data.businessNits.map(business => ({
      value: business.nit,
      label: business.name
    })),
    lines: options.data.lines.map(line => ({
      value: line.id,
      label: line.name
    }))
  };
  
  return filters;
}

3. Validación de parámetros optimizada

// Validación eficiente usando filtros específicos
async function validateHistoryParams(params) {
  const errors = [];
  
  // Validar solo lo que necesitas en lugar de obtener todas las opciones
  if (params.taskStatus) {
    const taskStatusOptions = await getSpecificOptions('task_status');
    const validStatuses = taskStatusOptions.data.taskStatus.map(s => s.id);
    
    if (!validStatuses.includes(params.taskStatus)) {
      errors.push(`Estado de tarea inválido: ${params.taskStatus}`);
    }
  }
  
  if (params.serviceType) {
    const serviceTypeOptions = await getSpecificOptions('service_type');
    const validTypes = serviceTypeOptions.data.serviceTypes.map(t => t.id);
    
    if (!validTypes.includes(params.serviceType)) {
      errors.push(`Tipo de servicio inválido: ${params.serviceType}`);
    }
  }
  
  if (params.businessNit) {
    const businessOptions = await getSpecificOptions('business_nit');
    const validNits = businessOptions.data.businessNits.map(b => b.nit);
    
    if (!validNits.includes(params.businessNit)) {
      errors.push(`NIT de empresa inválido: ${params.businessNit}`);
    }
  }
  
  return errors;
}

3. Interfaz de usuario

// Crear selectores dinámicos basados en las opciones
function createFilterSelectors(options) {
  const taskStatusSelect = document.getElementById('task-status-filter');
  const serviceTypeSelect = document.getElementById('service-type-filter');
  const businessSelect = document.getElementById('business-filter');
  
  // Limpiar opciones existentes
  taskStatusSelect.innerHTML = '<option value="">Todos los estados</option>';
  serviceTypeSelect.innerHTML = '<option value="">Todos los servicios</option>';
  businessSelect.innerHTML = '<option value="">Todas las empresas</option>';
  
  // Agregar opciones de estado de tarea
  options.data.taskStatus.forEach(status => {
    const option = document.createElement('option');
    option.value = status.id;
    option.textContent = status.name;
    taskStatusSelect.appendChild(option);
  });
  
  // Agregar opciones de tipo de servicio
  options.data.serviceTypes.forEach(service => {
    const option = document.createElement('option');
    option.value = service.id;
    option.textContent = service.name;
    serviceTypeSelect.appendChild(option);
  });
  
  // Agregar opciones de empresa
  options.data.businessNits.forEach(business => {
    const option = document.createElement('option');
    option.value = business.nit;
    option.textContent = business.name;
    businessSelect.appendChild(option);
  });
}

Manejo de errores

Errores comunes

Código	Descripción	Solución
401	No autorizado	Verificar credenciales de autenticación
403	Acceso denegado	Contactar soporte para permisos
500	Error interno del servidor	Reintentar la petición

Ejemplo de manejo de errores

async function getHistoryOptionsWithRetry(maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch('/api/v2/queries/history-options', {
        headers: {
          'Authorization': `Basic ${credentials}`
        }
      });
      
      if (response.ok) {
        return await response.json();
      } else if (response.status === 401) {
        throw new Error('Credenciales inválidas');
      } else if (response.status >= 500 && i < maxRetries - 1) {
        // Reintentar en errores del servidor
        await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
        continue;
      } else {
        throw new Error(`Error HTTP: ${response.status}`);
      }
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

Cachéo de opciones

Las opciones disponibles raramente cambian, por lo que se recomienda implementar un sistema de caché:

class HistoryOptionsCache {
  constructor(ttl = 3600000) { // 1 hora por defecto
    this.cache = null;
    this.timestamp = null;
    this.ttl = ttl;
  }
  
  async getOptions() {
    const now = Date.now();
    
    if (this.cache && this.timestamp && (now - this.timestamp) < this.ttl) {
      return this.cache;
    }
    
    const options = await this.fetchOptions();
    this.cache = options;
    this.timestamp = now;
    
    return options;
  }
  
  async fetchOptions() {
    const response = await fetch('/api/v2/queries/history-options', {
      headers: {
        'Authorization': `Basic ${credentials}`
      }
    });
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    
    return await response.json();
  }
  
  clearCache() {
    this.cache = null;
    this.timestamp = null;
  }
}

// Uso
const optionsCache = new HistoryOptionsCache();
const options = await optionsCache.getOptions();

Referencias

• Historial de Operaciones - Uso de estas opciones para filtrar el historial
• Autenticación - Configuración de credenciales
• Códigos de Respuesta - Manejo de errores estándar
• Ejemplos - Implementaciones completas

Notas adicionales

• Las opciones disponibles pueden variar según la configuración de tu cuenta
• Los códigos de estado y tipos de vehículo son específicos de cada integración
• Se recomienda obtener las opciones al inicializar la aplicación y cache la respuesta
• Contacta el soporte técnico si necesitas opciones adicionales o personalizadas

1. Optimización de consultas con filtro específico

// Función optimizada que solo obtiene lo que necesita
async function getSpecificOptions(filterType) {
  const response = await fetch(`[URL_API]/api/v2/queries/history-options?q=${filterType}`, {
    headers: {
      'Authorization': `Basic ${credentials}`
    }
  });
  
  return await response.json();
}

// Ejemplos específicos para diferentes necesidades:

// Solo para llenar un selector de estados
async function getTaskStatusDropdown() {
  const result = await getSpecificOptions('task_status');
  return result.data.taskStatus.map(status => ({
    value: status.id,
    text: status.name
  }));
}

// Solo para validar tipos de servicio
async function validateServiceType(serviceTypeId) {
  const result = await getSpecificOptions('service_type');
  const validIds = result.data.serviceTypes.map(type => type.id);
  return validIds.includes(serviceTypeId);
}

// Solo para obtener empresas disponibles
async function getAvailableCompanies() {
  const result = await getSpecificOptions('business_nit');
  return result.data.businessNits;
}