Tsalva API

Apariencia

Historial de Cambios - API TSALVA ​

Este documento mantiene un registro de todos los cambios notables realizados en la API de TSALVA.

El formato está basado en Keep a Changelog, y este proyecto adhiere al Semantic Versioning.

[3.0.0] - 2025-03-03 ​

Agregado ​

  • Módulo de Chat (/api/v3/chat/:expediente/*) - Mensajería en tiempo real entre cliente y técnico durante la ejecución del servicio, con historial paginado, contadores de no leídos y estadísticas
  • Módulo de Tracking (/api/v3/tracking/*) - Portal de seguimiento de servicios para el cliente final con verificación de identidad por código SMS (integración Twilio)
  • Endpoint GET /api/v3/offer-responses - Consulta en tiempo real de las respuestas recibidas durante el proceso de ofertamiento
  • Endpoint POST /api/v3/finalize - Finalización formal de servicios desde el lado del oferente, con soporte dual de autenticación (Basic + JWT)
  • Validación de integridad HMAC-SHA256 para los módulos de Chat y Tracking, previniendo ataques de replay con ventana de 5 minutos
  • Soporte para WebSockets en namespaces /v1, /v2 y /v3 (todos gestionados por el orquestador v3)

Cambiado ​

  • Las rutas /api/v1/* y /api/v2/* ahora redirigen automáticamente a /api/v3/* manteniendo compatibilidad total
  • Documentación actualizada para reflejar v3 como versión actual
  • Todos los ejemplos de código actualizados a /api/v3/

Deprecado ​

  • API v2 (/api/v2/*) - En proceso de deprecación. Sigue funcionando mediante redirección automática a v3, pero se recomienda migrar a /api/v3/
  • API v1 (/api/v1/*) - Obsoleta. Solo se mantiene por compatibilidad mediante redirección a v3

Notas de Migración (v2 → v3) ​

La migración de v2 a v3 es no disruptiva:

  1. Cambiar el prefijo de URL de /api/v2/ a /api/v3/
  2. Las credenciales existentes son compatibles sin cambios
  3. El formato de request/response de todos los endpoints existentes permanece idéntico
  4. Los nuevos endpoints (chat, tracking, finalize, offer-responses) son adiciones opcionales

[2.1.0] - 2024-01-15 ​

Agregado ​

  • Nuevo endpoint POST /api/v2/add-address para agregar direcciones adicionales
  • Soporte para múltiples paradas en una sola oferta
  • Campo notes opcional en todas las operaciones
  • Validación mejorada de coordenadas geográficas
  • Nuevo campo estimated_duration en respuestas de oferta

Cambiado ​

  • El campo callback_url ahora es opcional en ofertas
  • Mejoras en el tiempo de respuesta del endpoint /api/v2/types
  • Actualización del formato de timestamps a ISO 8601
  • Límite de rate limiting aumentado a 1000 peticiones/hora para cuentas premium

Corregido ​

  • Error en validación de coordenadas en regiones polares
  • Problema con caracteres especiales en direcciones
  • Inconsistencia en códigos de error HTTP

Seguridad ​

  • Implementación de HMAC-SHA256 para verificación de webhooks
  • Mejoras en la validación de entrada de datos
  • Actualización de dependencias de seguridad

[2.0.0] - 2023-12-01 ​

Agregado ​

  • Nueva versión de la API (v2) con arquitectura REST mejorada
  • Endpoint POST /api/v2/asignacion-directa para asignaciones específicas
  • Endpoint POST /api/v2/no-asignacion para marcar ofertas sin conductor
  • Sistema de webhooks para notificaciones en tiempo real
  • Soporte para diferentes tipos de vehículos
  • Sistema de prioridades (low, normal, high, urgent)
  • Endpoint GET /api/v2/queries/history-options para opciones de filtrado
  • Autenticación mejorada con tokens de sesión

Cambiado ​

  • BREAKING CHANGE: Migración de API v1 a v2
  • BREAKING CHANGE: Nuevo formato de respuesta estándar
  • BREAKING CHANGE: Cambio en estructura de datos de direcciones
  • Mejoras significativas en rendimiento
  • Nuevo sistema de códigos de error más detallado

Deprecado ​

  • API v1 será discontinuada el 2024-06-01
  • Endpoint legacy /api/request (usar /api/v2/oferta)
  • Formato de fecha YYYY-MM-DD (usar ISO 8601)

Removido ​

  • Soporte para autenticación con API key simple
  • Campos legacy pickup_time y delivery_time
  • Endpoint /api/status (reemplazado por /api/v2/queries/history)

Corregido ​

  • Problemas de concurrencia en asignaciones simultáneas
  • Error de timeout en operaciones de larga duración
  • Inconsistencias en respuestas de error

Seguridad ​

  • Implementación de rate limiting por usuario
  • Validación estricta de datos de entrada
  • Cifrado mejorado para datos sensibles

[1.5.2] - 2023-10-15 ​

Corregido ​

  • Error crítico en cálculo de distancias
  • Problema de memoria en consultas de historial extenso
  • Bug en validación de números de teléfono internacionales

Seguridad ​

  • Parche de seguridad para prevención de SQL injection
  • Actualización de certificados SSL

[1.5.1] - 2023-09-20 ​

Agregado ​

  • Soporte para coordenadas con mayor precisión (6 decimales)
  • Nuevo campo vehicle_capacity en tipos de vehículo

Cambiado ​

  • Mejoras en algoritmo de asignación de conductores
  • Optimización de consultas de base de datos

Corregido ​

  • Error en cálculo de ETA durante horas pico
  • Problema con caracteres UTF-8 en nombres de conductores

[1.5.0] - 2023-08-10 ​

Agregado ​

  • Endpoint GET /api/v1/driver/location para ubicación de conductores
  • Soporte para cancelaciones automáticas por timeout
  • Sistema de notificaciones push para aplicaciones móviles
  • Nuevos campos de metadatos en ofertas

Cambiado ​

  • Algoritmo de matching mejorado para asignaciones
  • Reducción en tiempo de respuesta promedio (30% más rápido)
  • Interfaz de administración actualizada

Corregido ​

  • Error en sincronización de estado entre servicios
  • Problema con duplicación de notificaciones

[1.4.0] - 2023-06-15 ​

Agregado ​

  • Sistema de evaluaciones y comentarios
  • Soporte para servicios programados
  • API para gestión de promociones y descuentos
  • Nuevos filtros en consultas de historial

Cambiado ​

  • Estructura de base de datos optimizada
  • Mejoras en el sistema de logging

Deprecado ​

  • Endpoint /api/v1/simple-request será removido en v2.0

[1.3.0] - 2023-04-20 ​

Agregado ​

  • Soporte para múltiples métodos de pago
  • Sistema de facturación automática
  • API para gestión de flotas empresariales
  • Reportes y analytics avanzados

Cambiado ​

  • Mejoras en el algoritmo de pricing dinámico
  • Optimización del sistema de webhooks

Corregido ​

  • Error en cálculo de tarifas en zonas especiales
  • Problema con timezone en diferentes regiones

[1.2.0] - 2023-02-10 ​

Agregado ​

  • Endpoint para tracking en tiempo real
  • Soporte para servicios de entrega de paquetes
  • Sistema de zonas geográficas
  • API para integración con sistemas de terceros

Cambiado ​

  • Interfaz de usuario mejorada para conductores
  • Optimización de consultas de geolocalización

[1.1.0] - 2023-01-05 ​

Agregado ​

  • Sistema básico de webhooks
  • Endpoint para consulta de historial
  • Soporte para diferentes tipos de servicio
  • Validaciones mejoradas de datos de entrada

Cambiado ​

  • Mejoras en manejo de errores
  • Documentación actualizada

Corregido ​

  • Error en asignación durante horarios de alta demanda
  • Problema con validación de coordenadas límite

[1.0.0] - 2022-12-01 ​

Agregado ​

  • Lanzamiento inicial de la API TSALVA
  • Endpoints básicos para crear ofertas
  • Sistema de autenticación HTTP Basic
  • Asignación automática de conductores
  • Estados básicos de seguimiento
  • Documentación inicial

Funcionalidades Principales ​

  • Creación de ofertas de servicio
  • Asignación de conductores
  • Cancelación de servicios
  • Consulta de tipos de vehículo
  • Sistema básico de notificaciones

Notas de Migración ​

Migración de v2 a v3 ​

La migración de v2 a v3 es completamente transparente ya que v1 y v2 redirigen automáticamente a v3. Sin embargo, para garantizar soporte a largo plazo:

# Antes (v2)
POST /api/v2/oferta
POST /api/v2/asignacion
POST /api/v2/cancelacion
GET  /api/v2/types

# Después (v3)
POST /api/v3/oferta
POST /api/v3/asignacion
POST /api/v3/cancelacion
GET  /api/v3/types

Solo se cambia el prefijo de versión. Las credenciales, headers, body y respuestas son idénticos.

Nuevas capacidades disponibles en v3:

  • Chat: GET|POST|PUT /api/v3/chat/:expediente/*
  • Tracking: POST /api/v3/tracking/requestCode|track|track/public|surveyresponse
  • Respuestas de oferta: GET /api/v3/offer-responses
  • Finalización: POST /api/v3/finalize

Migración de v1 a v2 ​

Cambios Principales ​

  1. URLs de Endpoints

    # v1
POST /api/request
GET /api/status/{id}

# v2
POST /api/v2/oferta
POST /api/v2/queries/history

  2. Formato de Respuesta

    json
    // v1
{
  "success": true,
  "data": {...}
}

// v2
{
  "status": "success",
  "data": {...},
  "metadata": {...}
}

  3. Estructura de Direcciones

    json
    // v1
{
  "pickup": "Dirección de origen",
  "destination": "Dirección de destino"
}

// v2
{
  "origen": {
    "lat": -34.6037,
    "lng": -58.3816,
    "address": "Dirección de origen"
  },
  "destino": {
    "lat": -34.6158,
    "lng": -58.3731,
    "address": "Dirección de destino"
  }
}

Cronograma de Migración ​

  • 2024-01-01: Liberación de API v2
  • 2024-02-01: Inicio del período de migración
  • 2024-04-01: API v1 marcada como deprecada
  • 2024-06-01: API v1 discontinuada completamente

Herramientas de Migración ​

  1. Script de Validación

    bash
    curl -X POST [URL_API]/migration/validate \
  -H "Authorization: Basic $(echo -n 'user:pass' | base64)" \
  -d '{"endpoint": "v1_endpoint_url"}'

  2. Mapeo de Datos

  3. Testing en Paralelo

Soporte Durante la Migración ​

Información de Soporte ​

Reportar Problemas ​

Solicitar Funcionalidades ​

Estado del Servicio ​

Documentación Adicional ​

Conveniones de Versionado ​

Este proyecto utiliza Semantic Versioning:

  • MAJOR: Cambios incompatibles en la API
  • MINOR: Funcionalidades agregadas de manera compatible
  • PATCH: Correcciones de bugs compatibles

Ejemplo de Numeración ​

  • 2.1.0 - Nueva funcionalidad menor
  • 2.1.1 - Corrección de bug
  • 3.0.0 - Cambio breaking

Política de Soporte ​

  • Versión Actual: Soporte completo y nuevas funcionalidades
  • Versión Anterior: Correcciones de bugs críticos por 12 meses
  • Versiones Antiguas: Sin soporte, migración recomendada

Última actualización: 2024-01-15

Tsalva API - Documentación desarrollada por RobPixels

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