Tsalva API - Introducción

⚠️ API v2 en proceso de deprecación

La versión v2 de la API está en proceso de deprecación. Aunque los endpoints /api/v2/* siguen funcionando (redirigen automáticamente a v3), se recomienda migrar a /api/v3/* lo antes posible.

Las credenciales existentes son compatibles con v3 sin cambios.

✅ Versión Actual: v3

API v3 es la versión actual y activa de la API TSALVA. Incluye todas las funcionalidades de v2 más nuevas capacidades de tracking de servicios y respuestas de oferta.

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
• Consultas históricas y reportería (exclusivo para usuarios del Gestor)
• Tracking de servicios con verificación por SMS
• 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
• Versiones anteriores: v2 (deprecada), v1 (deprecada)
• Protocolo: HTTPS
• Formato: JSON

Compatibilidad con versiones anteriores

La API v3 mantiene compatibilidad total hacia atrás. Los endpoints /api/v1/* y /api/v2/* redirigen automáticamente a v3, por lo que las integraciones existentes seguirán funcionando sin modificaciones. Sin embargo, se recomienda actualizar las URLs a /api/v3/* para garantizar soporte a largo plazo.

Prefijo	Estado	Comportamiento
/api/v3/	✅ Activo	Versión actual
/api/v2/	⚠️ Deprecado	Redirige a v3 automáticamente
/api/v1/	❌ Obsoleto	Redirige a v3 automáticamente

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
• Funcionalidades completas de la API

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
• Sistema de callbacks para notificaciones de aceptación (30s timeout)
• Selección automática del recurso más óptimo disponible
• Nuevo en v3: Consulta de respuestas de oferta en tiempo real (GET /offer-responses)

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 y Finalización

• Cancelación de servicios en cualquier estado
• Nuevo en v3: Finalización de servicios (POST /finalize)
• Soporte para servicios con múltiples consecutivos
• Notificación automática a centrales asignadas

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

Tracking de Servicios (nuevo en v3)

• Portal de seguimiento de servicio para el cliente final
• Verificación de identidad por código SMS (Twilio)
• Información pública y privada del servicio
• Encuestas de satisfacción post-servicio

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 creada
    API->>Central: Distribución automática
    Central->>API: Acepta oferta
    API->>Cliente: Callback de aceptación
    Cliente->>API: 2. POST /api/v3/asignacion
    API-->>Cliente: Detalles asignados
    Central->>API: Cambios de estado
    API->>Webhook: 3. Notificaciones webhook
    Cliente->>API: 4. POST /api/v3/finalize
    API-->>Cliente: Servicio finalizado

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
   • Tiempo de respuesta: 30 segundos para recibir aceptaciones

2. Recibir aceptación (callback 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.

5. Finalizar servicio (POST /api/v3/finalize) (nuevo en v3)

   • Cierre formal del servicio desde el lado del oferente

URL Base

La URL base de la API de TSALVA 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

Todas las peticiones deben realizarse a través de HTTPS.

https://[URL_PROPORCIONADA_AREA_DE_TI]

Autenticación

La mayoría de endpoints requieren autenticación básica HTTP. El módulo de Tracking utiliza validación de integridad HMAC-SHA256. Ver Autenticación para más detalles.

# Endpoints estándar
Authorization: Basic <credenciales_base64>

# Endpoints de Tracking (validación de integridad)
X-Integrity-Timestamp: <unix_timestamp>
X-Integrity-Signature: <hmac_sha256_hex>
X-Integrity-Algorithm: HMAC-SHA256
X-Integrity-Version: 1.0

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
• GET /api/v3/offer-responses - Consultar respuestas de oferta (nuevo v3)
• POST /api/v3/asignacion - Asignar detalles del cliente
• POST /api/v3/cancelacion - Cancelar servicio
• POST /api/v3/no-asignacion - Retirar oferta
• POST /api/v3/finalize - Finalizar servicio (nuevo v3)

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)

Tracking (nuevo en v3)

• POST /api/v3/tracking/requestCode - Solicitar código de verificación SMS
• POST /api/v3/tracking/track - Información del servicio (con verificación)
• POST /api/v3/tracking/track/public - Información pública del servicio
• POST /api/v3/tracking/surveyresponse - Enviar respuesta de encuesta

Webhooks

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

Límites y consideraciones

Límites de Rate

• Requests por minuto: 100
• Requests por hora: 2000

Timeouts

• Timeout de conexión: 30 segundos
• Timeout de webhook: 30 segundos
• Validez de integridad (tracking): 5 minutos (timestamp)

Reintentos

• Webhooks: Hasta 3 reintentos
• Intervalos: 1min, 5min, 15min

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 - Usa ejemplos de código
4. Configura webhooks - Ver configuración de webhooks

Soporte

¿Necesitas ayuda?

• Email: soporte@robpixels.com
• Documentación: ejemplos completos
• Status API: estado del servicio

---

Consejo

Revisa nuestros ejemplos de código para casos de uso específicos y mejores prácticas de integración.

Nota de migración

Si usas /api/v2/*, tus llamadas siguen funcionando. 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