Opciones de historial

El endpoint GET /api/v3/queries/history-options permite obtener las opciones disponibles para filtrar el historial de servicios en la API de TSALVA (estados, tipos de servicio, empresas, recursos, prestadores y líneas de negocio).

Endpoint

GET /api/v3/queries/history-options

Autenticación

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

Authorization: Basic <credentials>

Parámetros

Query Parameters

Parámetro	Tipo	Requerido	Descripción
q	string	No	Filtro para obtener solo un tipo de opción. Si se omite, se devuelven todas las 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 prestadores
• line - Líneas de negocio

Valor inválido de q

Si q tiene un valor distinto a los permitidos, la API responde 400 con el mensaje: Parámetro de consulta inválido. Valores permitidos: task_status, service_status, service_close_status, business_nit, service_type, resource_id, provider_nit, line.

Respuesta exitosa

Código de estado: 200 CorrectoMensaje (msg): Opciones de historial obtenidas correctamente

Estructura de la respuesta (sin q)

Cuando no se envía q, data contiene todas las colecciones de opciones:

{
  "status": true,
  "data": {
    "taskStatus": [
      { "id": 1, "name": "Pendiente" },
      { "id": 2, "name": "En proceso" }
    ],
    "serviceStatus": [
      { "id": 1, "name": "Activo" },
      { "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,
        "id_api": "GL",
        "name": "Grúa Liviana",
        "max_duration": 120,
        "minevidences": 3,
        "maneuver_time": 30,
        "mintask": 1,
        "required_skills": null,
        "form_required": 0,
        "business_line_id": 1,
        "auto_offer": 1,
        "updateOneByOne": 0,
        "clientSignature": 1
      }
    ],
    "resourceIds": [
      { "id": "TECH001", "name": "Carlos Rodríguez", "status": 1 },
      { "id": "TECH002", "name": "María González", "status": 1 }
    ],
    "providerNits": [
      { "nit": "PROV001", "name": "Proveedor Externo SA" }
    ],
    "lines": [
      { "id": 1, "line_name": "Grúas", "minimal_name": "GR" },
      { "id": 2, "line_name": "Mecánica", "minimal_name": "MEC" }
    ]
  },
  "msg": "Opciones de historial obtenidas correctamente"
}

Respuestas filtradas (con q)

Cuando se usa q, data solo contiene la clave correspondiente al filtro solicitado:

Valor de q	Clave devuelta en data
task_status	taskStatus
service_status	serviceStatus
service_close_status	serviceCloseStatus
business_nit	businessNits
service_type	serviceTypes
resource_id	resourceIds
provider_nit	providerNits
line	lines

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,
        "id_api": "GL",
        "name": "Grúa Liviana",
        "max_duration": 120,
        "minevidences": 3,
        "maneuver_time": 30,
        "mintask": 1,
        "required_skills": null,
        "form_required": 0,
        "business_line_id": 1,
        "auto_offer": 1,
        "updateOneByOne": 0,
        "clientSignature": 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 del estado de tarea.
• name: Nombre descriptivo del estado.

Estados de servicio (serviceStatus)

• id: Identificador del estado del servicio.
• name: Nombre descriptivo del estado.

Estados de cierre (serviceCloseStatus)

• id: Identificador del estado de cierre.
• name: Nombre descriptivo del estado.

NITs de empresas (businessNits)

• nit: NIT de la empresa (empresas con vínculo de tipo Proveedor).
• name: Nombre de la empresa (business_name).

Tipos de servicio (serviceTypes)

Devuelve los campos completos del tipo de servicio: id, id_api, name, max_duration, minevidences, maneuver_time, mintask, required_skills, form_required, business_line_id, auto_offer, updateOneByOne y clientSignature. La línea de negocio corresponde a business_line_id.

IDs de recursos (resourceIds)

• id: Identificador del recurso (docId).
• name: Nombre completo del recurso (names + lastname).
• status: Estado del recurso.

NITs de prestadores (providerNits)

• nit: NIT del prestador (empresas con vínculo de tipo Prestador).
• name: Nombre del prestador (business_name).

Líneas de negocio (lines)

• id: Identificador de la línea de negocio.
• line_name: Nombre de la línea de negocio.
• minimal_name: Nombre corto de la línea.

Errores

Código	Mensaje (msg)	Causa
400	Parámetro de consulta inválido. Valores permitidos: task_status, service_status, service_close_status, business_nit, service_type, resource_id, provider_nit, line.	El valor de q no está permitido.
401	No se han brindado las credenciales de acceso. / Las credenciales de acceso no son correctas.	Falta autenticación o credenciales inválidas.
404	Central no encontrada.	No se encontró la central asociada al usuario.
500	Error interno del servidor	Error inesperado (incluye campo error con el detalle).

Ejemplos de uso

cURL

Obtener todas las opciones

curl -X GET "[URL_API]/api/v3/queries/history-options" \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD"

Obtener solo estados de tarea

curl -X GET "[URL_API]/api/v3/queries/history-options?q=task_status" \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD"

Obtener solo tipos de servicio

curl -X GET "[URL_API]/api/v3/queries/history-options?q=service_type" \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD"

JavaScript

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

async function getHistoryOptions(filter = null) {
  const url = filter
    ? `[URL_API]/api/v3/queries/history-options?q=${filter}`
    : '[URL_API]/api/v3/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 {
  // Todas las opciones
  const todas = await getHistoryOptions();

  // Solo estados de servicio
  const estados = await getHistoryOptions('service_status');

  // Solo empresas
  const empresas = await getHistoryOptions('business_nit');

  console.log('Todas las opciones:', todas.data);
  console.log('Estados de servicio:', estados.data.serviceStatus);
  console.log('Empresas:', empresas.data.businessNits);
} catch (error) {
  console.error('Error:', error);
}

Python

import requests
from requests.auth import HTTPBasicAuth

def get_history_options(username, password, filter_type=None):
    url = '[URL_API]/api/v3/queries/history-options'
    params = {'q': filter_type} if filter_type else {}

    response = requests.get(
        url,
        auth=HTTPBasicAuth(username, password),
        params=params
    )
    response.raise_for_status()
    return response.json()

username = 'tu_usuario'
password = 'tu_password'

try:
    # Todas las opciones
    todas = get_history_options(username, password)

    # Solo estados de tarea
    estados_tarea = get_history_options(username, password, 'task_status')

    print("Tipos de servicio:")
    for tipo in todas['data']['serviceTypes']:
        print(f"- {tipo['name']} (ID: {tipo['id']}, Línea: {tipo['business_line_id']})")

    print("\nEmpresas:")
    for empresa in todas['data']['businessNits']:
        print(f"- {empresa['name']} (NIT: {empresa['nit']})")

    print("\nEstados de tarea:")
    for estado in estados_tarea['data']['taskStatus']:
        print(f"- {estado['name']} (ID: {estado['id']})")

except Exception as e:
    print(f"Error: {e}")

Casos de uso

Construcción de filtros para el historial

// Obtener todas las opciones para poblar los selectores de filtro
async function buildHistoryFilters() {
  const { data } = await getHistoryOptions();

  return {
    serviceStatus: data.serviceStatus.map(s => ({ value: s.id, label: s.name })),
    serviceTypes: data.serviceTypes.map(t => ({
      value: t.id,
      label: t.name,
      lineId: t.business_line_id
    })),
    businessNits: data.businessNits.map(b => ({ value: b.nit, label: b.name })),
    lines: data.lines.map(l => ({ value: l.id, label: l.line_name }))
  };
}

Obtención optimizada de un solo tipo de opción

// Solo lo necesario para poblar un selector de estados de servicio
async function getServiceStatusDropdown() {
  const { data } = await getHistoryOptions('service_status');
  return data.serviceStatus.map(s => ({ value: s.id, text: s.name }));
}

Caché

El servidor almacena en caché estas opciones (30 minutos). Las opciones cambian con poca frecuencia, por lo que también puedes cachearlas del lado del cliente e invalidarlas periódicamente.

Referencias

• Consultar Historial de Servicios - Uso de estas opciones para filtrar el historial.
• Autenticación - Configuración de credenciales.
• Códigos de Respuesta - Manejo de errores estándar.