Ejemplos de Código

Esta sección contiene ejemplos prácticos de integración con la API TSALVA en diferentes lenguajes de programación y herramientas.

🚀 Inicio Rápido

1. Flujo Básico de Oferta

El flujo más común de la API TSALVA:

graph LR
    A[Crear Oferta] --> B[Recibir Callback]
    B --> C[Asignar Detalles]
    C --> D[Recibir Webhooks]

2. Credenciales de Prueba

Contacta al equipo de TSALVA para obtener credenciales de sandbox:

📧 Email: soporte@robpixels.com
🔑 Solicitar: Credenciales de prueba
🌐 Ambiente: [URL_API] (proporcionada por RobPixels)

📚 Ejemplos por Tecnología

🌐 HTTP/cURL

Ver ejemplos completos

Ejemplos usando cURL desde la línea de comandos:

• Configuración de autenticación
• Todos los endpoints disponibles
• Scripts de automatización
• Manejo de errores

# Ejemplo rápido
curl -X POST "[URL_API]/api/v2/oferta" \
  --user "usuario:password" \
  -H "Content-Type: application/json" \
  -d '{"uuid": "...", "ciudad": "Medellín", ...}'

🟨 JavaScript/Node.js

Ver ejemplos completos

Implementaciones para aplicaciones web y Node.js:

• Cliente HTTP con fetch/axios
• Manejo de callbacks y webhooks
• Validación de respuestas
• Casos de uso comunes

const response = await fetch('/api/v2/oferta', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(datosOferta)
});

🐍 Python

Ver ejemplos completos

Código para aplicaciones Python:

• Cliente con requests
• Framework Flask/Django
• Manejo asíncrono
• Integración con bases de datos

import requests
from requests.auth import HTTPBasicAuth

response = requests.post(
    '[URL_API]/api/v2/oferta',
    auth=HTTPBasicAuth('usuario', 'password'),
    json=datos_oferta
)

🐘 PHP

Ver ejemplos completos

Implementaciones para aplicaciones PHP:

• Cliente con cURL
• Framework Laravel/Symfony
• Webhooks con PHP
• Manejo de errores

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => '[URL_API]/api/v2/oferta',
    CURLOPT_USERPWD => 'usuario:password',
    CURLOPT_POSTFIELDS => json_encode($datos),
]);

🎯 Casos de Uso Comunes

1. Servicio de Grúa Básico

// Crear oferta para grúa liviana
const ofertaGrua = {
  uuid: generateUUID(),
  ciudad: 'Medellín',
  departamento: 'Antioquia',
  latitudOrigen: 6.2442,
  longitudOrigen: -75.5812,
  direccionOrigen: 'Autopista Norte Km 15',
  tipoServicio: '2', // Grúa Liviana
  descripcionServicio: 'Vehículo averiado requiere traslado a taller',
  callbackUrl: 'https://tu-app.com/callback/aceptacion'
};

2. Conductor Elegido

// Servicio de conductor para vehículo del cliente
const ofertaConductor = {
  uuid: generateUUID(),
  ciudad: 'Bogotá',
  departamento: 'Cundinamarca',
  latitudOrigen: 4.6097,
  longitudOrigen: -74.0817,
  direccionOrigen: 'Zona Rosa, Calle 82',
  tipoServicio: '1', // Conductor elegido
  descripcionServicio: 'Cliente requiere conductor para su vehículo'
};

3. Asignación Directa Programada

// Servicio programado con central específica
const servicioprogramado = {
  uuid: generateUUID(),
  dniPrestador: '900123456',
  tipoServicio: '4', // Ambulancia
  fechaCita: '2025-07-05',
  horaCita: '10:30',
  descripcionServicio: 'Traslado médico programado',
  // ... ubicaciones y datos del cliente
};

🔧 Utilidades y Helpers

Generador de UUID

// JavaScript
function generateUUID() {
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
    const r = Math.random() * 16 | 0;
    const v = c == 'x' ? r : (r & 0x3 | 0x8);
    return v.toString(16);
  });
}

# Python
import uuid

def generate_uuid():
    return str(uuid.uuid4())

// PHP
function generateUUID() {
    return sprintf('%04x%04x-%04x-%04x-%04x-%04x%04x%04x',
        mt_rand(0, 0xffff), mt_rand(0, 0xffff),
        mt_rand(0, 0xffff),
        mt_rand(0, 0x0fff) | 0x4000,
        mt_rand(0, 0x3fff) | 0x8000,
        mt_rand(0, 0xffff), mt_rand(0, 0xffff), mt_rand(0, 0xffff)
    );
}

Validador de Coordenadas

function validarCoordenadas(lat, lng) {
  const latNum = parseFloat(lat);
  const lngNum = parseFloat(lng);
  
  if (isNaN(latNum) || isNaN(lngNum)) {
    throw new Error('Coordenadas deben ser números válidos');
  }
  
  if (latNum < -90 || latNum > 90) {
    throw new Error('Latitud debe estar entre -90 y 90');
  }
  
  if (lngNum < -180 || lngNum > 180) {
    throw new Error('Longitud debe estar entre -180 y 180');
  }
  
  return { lat: latNum, lng: lngNum };
}

Cliente API Reutilizable

class TSALVAClient {
  constructor(username, password, baseUrl = '[URL_API]') {
    this.auth = btoa(`${username}:${password}`);
    this.baseUrl = baseUrl;
  }
  
  async request(method, endpoint, data = null) {
    const config = {
      method,
      headers: {
        'Authorization': `Basic ${this.auth}`,
        'Content-Type': 'application/json'
      }
    };
    
    if (data) {
      config.body = JSON.stringify(data);
    }
    
    const response = await fetch(`${this.baseUrl}${endpoint}`, config);
    const result = await response.json();
    
    if (!response.ok || !result.status) {
      throw new Error(result.msg || `HTTP ${response.status}`);
    }
    
    return result;
  }
  
  async crearOferta(datos) {
    return this.request('POST', '/api/v2/oferta', datos);
  }
  
  async asignarDetalles(datos) {
    return this.request('POST', '/api/v2/asignacion', datos);
  }
  
  async obtenerTipos() {
    const response = await fetch(`${this.baseUrl}/api/v2/types`, {
      headers: { 'Authorization': `Basic ${this.auth}` }
    });
    return response.json();
  }
}

// Uso
const cliente = new TSALVAClient('usuario', 'password');
const tipos = await cliente.obtenerTipos();

🔄 Patrones de Integración

1. Patrón Observer (Webhooks)

sequenceDiagram
    participant App as Tu App
    participant API as TSALVA API
    participant Central
    participant Webhook as Tu Webhook

    App->>API: Crear oferta
    API->>Central: Distribuir
    Central->>API: Aceptar
    API->>Webhook: Notificar aceptación
    Central->>API: Cambio estado
    API->>Webhook: Notificar cambio

2. Patrón Polling (Consultas)

// Verificar estado periódicamente
async function monitorearServicio(idServicio) {
  const interval = setInterval(async () => {
    try {
      const historial = await cliente.consultarHistorial({
        line: '1',
        autNumber: idServicio
      });
      
      const servicio = historial.data[0];
      if (servicio && servicio.estado === 'Completado') {
        console.log('Servicio completado');
        clearInterval(interval);
      }
    } catch (error) {
      console.error('Error consultando estado:', error);
    }
  }, 30000); // Cada 30 segundos
}

3. Patrón Circuit Breaker

class CircuitBreaker {
  constructor(failureThreshold = 5, timeout = 60000) {
    this.failureThreshold = failureThreshold;
    this.timeout = timeout;
    this.failureCount = 0;
    this.lastFailureTime = null;
    this.state = 'CLOSED'; // CLOSED, OPEN, HALF_OPEN
  }
  
  async call(fn) {
    if (this.state === 'OPEN') {
      if (Date.now() - this.lastFailureTime > this.timeout) {
        this.state = 'HALF_OPEN';
      } else {
        throw new Error('Circuit breaker is OPEN');
      }
    }
    
    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }
  
  onSuccess() {
    this.failureCount = 0;
    this.state = 'CLOSED';
  }
  
  onFailure() {
    this.failureCount++;
    this.lastFailureTime = Date.now();
    
    if (this.failureCount >= this.failureThreshold) {
      this.state = 'OPEN';
    }
  }
}

📊 Testing y Debugging

Test de Conectividad

# Script de verificación rápida
curl -f -s --user "usuario:password" \
  "[URL_API]/api/v2/types" > /dev/null && \
  echo "✅ API funcionando" || \
  echo "❌ API no disponible"

Logs Estructurados

const winston = require('winston');

const logger = winston.createLogger({
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.json()
  ),
  transports: [
    new winston.transports.Console(),
    new winston.transports.File({ filename: 'tsalva-api.log' })
  ]
});

// Usar en llamadas API
logger.info('Creando oferta', { 
  uuid: oferta.uuid, 
  tipo: oferta.tipoServicio 
});

---

¿Nuevo en APIs REST?

Si eres nuevo trabajando con APIs REST, te recomendamos empezar con los ejemplos de cURL para familiarizarte con los endpoints antes de implementar en tu lenguaje preferido.

Importante

Todos los ejemplos utilizan URLs de producción. Para pruebas, solicita acceso al ambiente de sandbox del equipo de TSALVA.