Tsalva API

Apariencia

Ejemplos con cURL ​

Esta sección proporciona ejemplos completos de uso de la API TSALVA utilizando cURL. Estos ejemplos pueden ser usados directamente desde la línea de comandos o adaptados para scripts automatizados.

📍 Importante: En todos los ejemplos de este documento, reemplaza [URL_API] con la URL base proporcionada por el área de TI de RobPixels. Para obtenerla, contacta: gerencia@robpixels.com o soporte@robpixels.com

Variables de Entorno ​

Configura tus credenciales como variables de entorno:

bash
# Exportar credenciales
export TSALVA_USERNAME="tu_usuario"
export TSALVA_PASSWORD="tu_password"
export TSALVA_BASE_URL="[URL_API]"

# Verificar configuración
echo "Usuario: $TSALVA_USERNAME"
echo "URL Base: $TSALVA_BASE_URL"

Autenticación Básica ​

bash
# Opción 1: Usar --user (recomendado)
curl --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
     -H "Content-Type: application/json" \
     "$TSALVA_BASE_URL/api/v2/types"

# Opción 2: Header Authorization manual
AUTH_HEADER=$(echo -n "$TSALVA_USERNAME:$TSALVA_PASSWORD" | base64)
curl -H "Authorization: Basic $AUTH_HEADER" \
     -H "Content-Type: application/json" \
     "$TSALVA_BASE_URL/api/v2/types"

Consultas (GET) ​

Obtener Tipos de Servicio ​

bash
curl -X GET "$TSALVA_BASE_URL/api/v2/types" \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
  -H "Content-Type: application/json"

Respuesta esperada:

json
[
  {
    "id": 1,
    "type": "Conductor elegido",
    "required_origin": true,
    "required_destination": false
  },
  {
    "id": 2,
    "type": "Grúa Liviana",
    "required_origin": true,
    "required_destination": true
  }
]

Obtener Opciones de Historial ​

bash
# Todas las opciones
curl -X GET "$TSALVA_BASE_URL/api/v2/queries/history-options" \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
  -H "Content-Type: application/json"

# Solo estados de tareas
curl -X GET "$TSALVA_BASE_URL/api/v2/queries/history-options?q=task_status" \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
  -H "Content-Type: application/json"

Crear Oferta de Servicio ​

Ejemplo Básico ​

bash
curl -X POST "$TSALVA_BASE_URL/api/v2/oferta" \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "ciudad": "Medellín",
    "departamento": "Antioquia",
    "latitudOrigen": 6.2442,
    "longitudOrigen": -75.5812,
    "direccionOrigen": "Carrera 25A #1A Sur-45",
    "tipoServicio": "1",
    "descripcionServicio": "Grúa liviana para automóvil averiado"
  }'

Ejemplo Completo con Destino y Callback ​

bash
curl -X POST "$TSALVA_BASE_URL/api/v2/oferta" \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "ciudad": "Medellín",
    "departamento": "Antioquia",
    "latitudOrigen": 6.2442,
    "longitudOrigen": -75.5812,
    "puntoReferenciaOrigen": "Frente al centro comercial El Tesoro",
    "direccionOrigen": "Carrera 25A #1A Sur-45",
    "latitudDestino": 6.2518,
    "longitudDestino": -75.5636,
    "puntoReferenciaDestino": "Hospital Pablo Tobón Uribe",
    "direccionDestino": "Calle 78B #69-240",
    "fechaCita": "2025-07-03",
    "horaCita": "14:30",
    "observaciones": "Vehículo con falla mecánica en el motor",
    "descripcionServicio": "Grúa liviana para traslado de automóvil averiado",
    "tipoServicio": "2",
    "callbackUrl": "https://tu-servidor.com/api/webhook/aceptacion"
  }'

Con Archivo JSON ​

bash
# Crear archivo oferta.json
cat > oferta.json << 'EOF'
{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "ciudad": "Bogotá",
  "departamento": "Cundinamarca",
  "latitudOrigen": 4.6097,
  "longitudOrigen": -74.0817,
  "direccionOrigen": "Calle 26 #57-83",
  "tipoServicio": "1",
  "descripcionServicio": "Conductor para vehículo del cliente",
  "callbackUrl": "https://tu-servidor.com/callback"
}
EOF

# Enviar oferta
curl -X POST "$TSALVA_BASE_URL/api/v2/oferta" \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
  -H "Content-Type: application/json" \
  -d @oferta.json

Asignar Detalles del Cliente ​

bash
curl -X POST "$TSALVA_BASE_URL/api/v2/asignacion" \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "codigoServicio": "TSV202507030001",
    "riesgo": "POL-2025-001234",
    "primerNombre": "Carlos",
    "segundoNombre": "Andrés",
    "primerApellido": "Rodríguez",
    "segundoApellido": "García",
    "telefonoSolicitante": "+57 300-123-4567",
    "telefonoSolicitante2": "+57 301-234-5678",
    "claseVehiculo": "Automóvil",
    "marcaVehiculo": "Toyota",
    "tipoTransmisionVehiculo": "Automática",
    "observaciones": "Cliente prefiere contacto vía WhatsApp"
  }'

Asignación Directa ​

Ejemplo Mínimo ​

bash
curl -X POST "$TSALVA_BASE_URL/api/v2/asignacion-directa" \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "123e4567-e89b-12d3-a456-426614174001",
    "dniPrestador": "900123456",
    "tipoServicio": "1",
    "descripcionServicio": "Grúa liviana urgente",
    "latitudOrigen": "6.2442",
    "longitudOrigen": "-75.5812",
    "direccionOrigen": "Autopista Norte Km 15",
    "ciudad": "Medellín",
    "departamento": "Antioquia"
  }'

Ejemplo Completo ​

bash
curl -X POST "$TSALVA_BASE_URL/api/v2/asignacion-directa" \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "123e4567-e89b-12d3-a456-426614174001",
    "dniPrestador": "900123456",
    "dniGenerador": "98765432",
    "tipoServicio": "2",
    "descripcionServicio": "Grúa liviana para vehículo averiado",
    "latitudOrigen": "6.2442",
    "longitudOrigen": "-75.5812",
    "puntoReferenciaOrigen": "Autopista Norte Km 15, carril de emergencia",
    "direccionOrigen": "Autopista Norte Km 15",
    "latitudDestino": "6.2518",
    "longitudDestino": "-75.5636",
    "puntoReferenciaDestino": "Taller Los Ángeles",
    "direccionDestino": "Calle 78B #69-240",
    "ciudad": "Medellín",
    "departamento": "Antioquia",
    "fechaCita": "2025-07-03",
    "horaCita": "16:30",
    "observaciones": "Vehículo en carril de emergencia",
    "codigoServicio": "GOT00356",
    "riesgo": "POL-2025-001234",
    "primerNombre": "Carlos",
    "primerApellido": "Rodríguez",
    "telefonoSolicitante": "+57 300-123-4567",
    "claseVehiculo": "Automóvil",
    "marcaVehiculo": "Toyota"
  }'

Cancelaciones ​

Cancelar Servicio Simple ​

bash
curl -X POST "$TSALVA_BASE_URL/api/v2/cancelacion" \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "idServicio": "TSV202507030001",
    "razon": "Cliente solucionó el problema por cuenta propia"
  }'

Cancelar con Código de Solicitud ​

bash
curl -X POST "$TSALVA_BASE_URL/api/v2/cancelacion" \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "idServicio": "TSV202507030001",
    "razon": "Cambio de ubicación del cliente",
    "codigoSolicitud": "MOV01"
  }'

Retirar Oferta ​

bash
curl -X POST "$TSALVA_BASE_URL/api/v2/no-asignacion" \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  }'

Agregar Dirección Adicional ​

bash
curl -X POST "$TSALVA_BASE_URL/api/v2/add-address" \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "latitudDireccion": "6.2500",
    "longitudDireccion": "-75.5700",
    "puntoReferenciaDireccion": "Estación de gasolina Texaco",
    "direccion": "Carrera 65 #45-30",
    "observaciones": "Parada adicional para combustible"
  }'

Consultas Históricas ​

Por Número de Autorización ​

bash
curl -X POST "$TSALVA_BASE_URL/api/v2/queries/history" \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "line": "1",
    "autNumber": "TSV12345678"
  }'

Por Rango de Fechas ​

bash
curl -X POST "$TSALVA_BASE_URL/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"
  }'

Con Filtros Adicionales ​

bash
curl -X POST "$TSALVA_BASE_URL/api/v2/queries/history" \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "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"]
  }'

Scripts de Automatización ​

Script de Flujo Completo ​

bash
#!/bin/bash

# Configuración
export TSALVA_USERNAME="tu_usuario"
export TSALVA_PASSWORD="tu_password"
export TSALVA_BASE_URL="[URL_API]"

UUID=$(uuidgen)
echo "Creando oferta con UUID: $UUID"

# 1. Crear oferta
echo "1. Creando oferta..."
OFERTA_RESPONSE=$(curl -s -X POST "$TSALVA_BASE_URL/api/v2/oferta" \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "'$UUID'",
    "ciudad": "Medellín",
    "departamento": "Antioquia",
    "latitudOrigen": 6.2442,
    "longitudOrigen": -75.5812,
    "direccionOrigen": "Carrera 25A #1A Sur-45",
    "tipoServicio": "1",
    "descripcionServicio": "Grúa liviana para automóvil"
  }')

echo "Respuesta oferta: $OFERTA_RESPONSE"

# Verificar éxito
if echo "$OFERTA_RESPONSE" | grep -q '"status":true'; then
    echo "✅ Oferta creada exitosamente"
    
    # 2. Esperar un momento (simular callback)
    echo "2. Esperando aceptación..."
    sleep 5
    
    # 3. Asignar detalles
    echo "3. Asignando detalles del cliente..."
    ASIGNACION_RESPONSE=$(curl -s -X POST "$TSALVA_BASE_URL/api/v2/asignacion" \
      --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
      -H "Content-Type: application/json" \
      -d '{
        "uuid": "'$UUID'",
        "codigoServicio": "TSV'$(date +%Y%m%d%H%M%S)'",
        "riesgo": "POL-2025-001234",
        "primerNombre": "Carlos",
        "primerApellido": "Rodríguez",
        "telefonoSolicitante": "+57 300-123-4567"
      }')
    
    echo "Respuesta asignación: $ASIGNACION_RESPONSE"
    
    if echo "$ASIGNACION_RESPONSE" | grep -q '"status":true'; then
        echo "✅ Servicio completamente configurado"
    else
        echo "❌ Error en asignación"
    fi
    
else
    echo "❌ Error creando oferta"
fi

Script de Validación de Conectividad ​

bash
#!/bin/bash

echo "🔍 Validando conectividad con API TSALVA..."

# Test 1: Conectividad básica
echo "1. Probando conectividad básica..."
if curl -s --connect-timeout 10 "$TSALVA_BASE_URL" > /dev/null; then
    echo "✅ Servidor accesible"
else
    echo "❌ No se puede conectar al servidor"
    exit 1
fi

# Test 2: Autenticación
echo "2. Probando autenticación..."
AUTH_RESPONSE=$(curl -s -w "%{http_code}" -o /dev/null \
  --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
  "$TSALVA_BASE_URL/api/v2/types")

if [ "$AUTH_RESPONSE" = "200" ]; then
    echo "✅ Autenticación correcta"
elif [ "$AUTH_RESPONSE" = "401" ]; then
    echo "❌ Credenciales inválidas"
    exit 1
else
    echo "⚠️ Respuesta inesperada: $AUTH_RESPONSE"
fi

# Test 3: Endpoint funcional
echo "3. Probando endpoint de tipos..."
TYPES_RESPONSE=$(curl -s --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
  "$TSALVA_BASE_URL/api/v2/types")

if echo "$TYPES_RESPONSE" | grep -q "type"; then
    echo "✅ API funcionando correctamente"
    echo "📋 Tipos disponibles:"
    echo "$TYPES_RESPONSE" | jq -r '.[] | "  - \(.id): \(.type)"' 2>/dev/null || echo "$TYPES_RESPONSE"
else
    echo "❌ Respuesta de API inválida"
fi

echo "🎉 Validación completada"

Manejo de Errores ​

Script con Manejo de Errores ​

bash
#!/bin/bash

# Función para manejar errores
handle_error() {
    local response="$1"
    local operation="$2"
    
    if echo "$response" | grep -q '"status":false'; then
        local error_msg=$(echo "$response" | jq -r '.msg' 2>/dev/null || echo "Error desconocido")
        echo "❌ Error en $operation: $error_msg"
        return 1
    fi
    
    echo "✅ $operation exitoso"
    return 0
}

# Crear oferta con manejo de errores
create_offer() {
    local uuid="$1"
    
    local response=$(curl -s -X POST "$TSALVA_BASE_URL/api/v2/oferta" \
      --user "$TSALVA_USERNAME:$TSALVA_PASSWORD" \
      -H "Content-Type: application/json" \
      -d '{
        "uuid": "'$uuid'",
        "ciudad": "Medellín",
        "departamento": "Antioquia",
        "latitudOrigen": 6.2442,
        "longitudOrigen": -75.5812,
        "direccionOrigen": "Carrera 25A #1A Sur-45",
        "tipoServicio": "1",
        "descripcionServicio": "Grúa liviana"
      }')
    
    if handle_error "$response" "creación de oferta"; then
        echo "Oferta creada con UUID: $uuid"
        return 0
    else
        return 1
    fi
}

# Uso
UUID=$(uuidgen)
create_offer "$UUID"

Consejo

Guarda estos comandos en archivos .sh y hazlos ejecutables con chmod +x archivo.sh para automatizar tus pruebas y operaciones frecuentes.

Importante

Nunca hardcodees credenciales en scripts. Usa siempre variables de entorno o archivos de configuración seguros.

Tsalva API - Documentación desarrollada por RobPixels

Copyright © 2025 TSALVA & RobPixels SAS · Para acceso a la API contacta: gerencia@robpixels.com