Tsalva API - Introducción

✅ Versión Actual: v3

API v3 es la versión actual y activa de la API TSALVA. Todo el tráfico se atiende a través del router de v3.

Versionado

Los prefijos /api/v1/* y /api/v2/* se mantienen únicamente por compatibilidad: son alias que se resuelven internamente con el mismo router de v3. No hay lógica separada de v1/v2; se recomienda usar siempre /api/v3/*.

Información General

La Tsalva API es una API RESTful diseñada para la gestión integral de servicios de asistencia en la plataforma TSALVA. Esta API facilita la integración tanto a empresas externas como a empresas que actualmente utilizan el Gestor TSALVA, permitiendo realizar operaciones completas de:

• Ofertamiento y asignación de servicios
• Cancelación y gestión de estados
• Asignación directa de servicios pre-acordados
• Consultas históricas y reportería (exclusivo para usuarios del Gestor)
• Notificaciones en tiempo real mediante webhooks

Tipos de servicios soportados

• Asistencia vial (grúas, mecánica, combustible)
• Servicios del hogar (plomería, electricidad, cerrajería)
• Servicios de salud (ambulancias, traslados médicos)
• Servicios jurídicos (asesoría legal, trámites)
• Transporte (logística, mudanzas, entregas)

Versión

• Versión actual: 3.0
• Prefijos anteriores: v2 y v1 (alias hacia v3)
• Protocolo: HTTPS
• Formato: JSON

Compatibilidad con versiones anteriores

Los endpoints /api/v1/* y /api/v2/* se resuelven con el mismo router de v3, por lo que las integraciones existentes seguirán funcionando sin modificaciones. Aun así, se recomienda actualizar las URLs a /api/v3/*.

Prefijo	Estado	Comportamiento
/api/v3/	✅ Activo	Versión actual
/api/v2/	⚠️ Alias	Atendido por el router de v3
/api/v1/	⚠️ Alias	Atendido por el router de v3

Tipos de usuarios y casos de uso

Empresas externas

• Integración para ofertamiento y asignación de servicios
• Flujo operativo: oferta → aceptación → asignación → seguimiento
• Gestión de cancelaciones y notificaciones webhook
• Nota: No tienen acceso a consultas históricas

Empresas con Gestor TSALVA

• Integración de sistemas internos con el Gestor TSALVA existente
• Acceso exclusivo a consultas históricas para reportería y análisis
• Sincronización de datos entre sistemas
• Automatización de procesos internos

Características Principales

Ofertamiento de Servicios

• Creación y gestión de ofertas de servicio
• Distribución inteligente automática con algoritmo de optimización
• Evaluación multi-criterio: permisos, cobertura, recursos y disponibilidad
• Notificación de aceptación mediante webhook
• Selección automática del recurso más óptimo disponible

Asignación Directa

• Asignación directa de servicios a centrales específicas
• Ideal para servicios pre-acordados o programados
• Creación completa en una sola petición

Gestión de Cancelaciones

• Cancelación de servicios en cualquier estado
• Soporte para servicios con múltiples consecutivos
• Notificación automática a la central asignada

Consultas y Reportes

• Consultas históricas con filtros avanzados (exclusivo para usuarios del Gestor TSALVA)
• Exportación de datos para análisis y reportería empresarial
• Opciones de filtrado configurables para integración de sistemas

Webhooks

• Notificaciones en tiempo real de cambios de estado
• Configuración flexible de endpoints
• Reintentos automáticos en caso de errores

Flujo de Trabajo Típico

sequenceDiagram
    participant Cliente
    participant API as Tsalva API v3
    participant Central
    participant Webhook as Cliente Webhook

    Cliente->>API: 1. POST /api/v3/oferta
    API-->>Cliente: Oferta recibida
    API->>Central: Distribución automática
    Central->>API: Acepta oferta
    API->>Cliente: Notificación de aceptación (webhook)
    Cliente->>API: 2. POST /api/v3/asignacion
    API-->>Cliente: Detalles asignados
    Central->>API: Cambios de estado
    API->>Webhook: 3. Notificaciones webhook

Paso a paso:

1. Crear oferta (POST /api/v3/oferta)

   • Se registra una nueva solicitud de servicio
   • Distribución inteligente automática: El sistema evalúa y filtra centrales según múltiples criterios

2. Recibir aceptación (webhook)

   • El sistema selecciona automáticamente la mejor oferta
   • Se envía notificación mediante webhook con datos del prestador, técnico y tiempos estimados

3. Asignar detalles (POST /api/v3/asignacion)

   • Se completan los datos del cliente y vehículo
   • El servicio queda listo para ejecución

4. Recibir notificaciones (webhooks)

   • Se reciben actualizaciones en tiempo real
   • Estados: en camino, en sitio, completado, etc.

URL Base

Todas las peticiones se realizan a través de HTTPS sobre el prefijo /api/v3:

[URL_API]/api/v3

La URL base ([URL_API]) debe ser solicitada al área de TI de RobPixels.

Para obtener acceso a la API:

• Gerencia: gerencia@robpixels.com
• Soporte Técnico: soporte@robpixels.com

Autenticación

La mayoría de los endpoints usan autenticación básica HTTP (Authorization: Basic <credenciales_base64>). El único endpoint que usa un esquema distinto es PUT /aceptacion, que se valida mediante API key (header x-apikey). Ver Autenticación para más detalles.

# Endpoints estándar (Basic Auth)
Authorization: Basic <credenciales_base64>

# PUT /aceptacion (API key)
x-apikey: <clave_de_acceso>

Códigos de Respuesta

La API utiliza códigos de estado HTTP estándar. Ver Códigos de respuesta para más información.

Endpoints Disponibles

Ofertamiento y Asignación

• POST /api/v3/oferta - Crear oferta de servicio
• POST /api/v3/asignacion - Asignar detalles del cliente
• POST /api/v3/no-asignacion - Retirar oferta
• POST /api/v3/cancelacion - Cancelar servicio

Servicios Directos

• POST /api/v3/asignacion-directa - Crear y asignar directamente
• POST /api/v3/add-address - Agregar dirección adicional

Consultas

• GET /api/v3/types - Consultar tipos de servicio
• POST /api/v3/queries/history - Consultar historial (solo Gestor TSALVA)
• GET /api/v3/queries/history-options - Opciones de filtrado (solo Gestor TSALVA)

Aceptación (API key)

• PUT /api/v3/aceptacion - Aceptar oferta desde una central (autenticación por x-apikey)

Webhooks

• PUT /webhooks/cambio-estado - Notificación de cambios de estado

Límites y consideraciones

Rate limiting

• El endpoint de login (/api/v3/users/login) está protegido contra fuerza bruta: 5 intentos por 15 minutos por IP. Al excederlo se devuelve 429.
• El límite global de API está definido en el código pero no está activado actualmente (varios usuarios legítimos pueden compartir IP/NAT).

Timeouts

• Timeout de conexión: 60 segundos (connect-timeout). Si se excede, la API responde 408.

Reintentos

• Webhooks: reintentos automáticos ante errores de entrega.

Primeros Pasos

1. Obtén credenciales - Contacta al equipo de TSALVA
2. Configura autenticación - Ver guía de autenticación
3. Prueba tu primera oferta - Ver POST /api/v3/oferta
4. Configura webhooks - Ver configuración de webhooks

Soporte

¿Necesitas ayuda?

• Email: soporte@robpixels.com
• Gerencia: gerencia@robpixels.com

---

Nota de migración

Si usas /api/v2/* o /api/v1/*, tus llamadas siguen funcionando (se atienden con el router de v3). Para migrar, simplemente cambia el prefijo a /api/v3/. Las credenciales y el formato de los cuerpos de petición son idénticos.

Importante: En todos los ejemplos de esta documentación, [URL_API] debe ser reemplazado por la URL base proporcionada por RobPixels. Para obtenerla, contacta: gerencia@robpixels.com o soporte@robpixels.com