Tsalva API

Apariencia

Tsalva API - Introducción ​

🆕 Novedades ​

✨ Nuevos Endpoints Disponibles

Endpoints de Consulta Histórica - ¡Ahora disponibles para usuarios del Gestor TSALVA!

Nuevas funcionalidades:

Beneficios:

  • Reportería avanzada e integración de datos
  • Filtros configurables por fechas, estados, tipos de servicio
  • Exportación para análisis empresarial
  • Sincronización con sistemas internos

Importante: Estos endpoints están disponibles exclusivamente para empresas que utilizan el Gestor TSALVA

Próximamente

Se están desarrollando nuevos endpoints para ampliar las capacidades de integración. ¡Mantente atento a futuras actualizaciones!

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)
  • 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: 1.0
  • Protocolo: HTTPS
  • Formato: JSON

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

📈 Expansión continua: Se están desarrollando constantemente nuevos endpoints específicos para mejorar la integración con el Gestor TSALVA, incluyendo funcionalidades avanzadas de reportería, análisis y gestión de datos.

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

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 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
  • Sincronización de datos entre plataformas internas

🔒 Acceso restringido: Las funcionalidades de consulta histórica están disponibles únicamente para empresas que utilizan el Gestor TSALVA, no para integraciones externas.

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 ​

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

    Cliente->>API: 1. POST /api/v2/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/v2/asignacion
    API-->>Cliente: Detalles asignados
    Central->>API: Cambios de estado
    API->>Webhook: 3. Notificaciones webhook

Paso a paso: ​

  1. Crear oferta (POST /api/v2/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:

      Filtrado inicial de centrales:

      • Permisos para aceptar servicios del oferente
      • Cobertura geográfica (poblaciones atendidas)
      • Tipos de servicios autorizados

      Evaluación de recursos técnicos:

      • Habilidades específicas para el tipo de servicio
      • Proximidad geográfica del técnico al lugar del servicio
      • Disponibilidad (sin bloqueos por ausencias)
      • Estado operativo (no esperando otras asignaciones)
      • Agenda libre (sin servicios en el mismo horario)

      Selección óptima:

      • Prioridades de central y técnico
      • Algoritmo de optimización para el mejor recurso disponible
      • Tiempo de respuesta: 30 segundos para recibir aceptaciones
      • Selección final: Se acepta la respuesta que mejor se ajuste a los criterios

  2. Recibir aceptación (callback)

    • Tras evaluar todas las respuestas recibidas en el período de 30 segundos
    • El sistema selecciona automáticamente la mejor oferta basado en los criterios de optimización
    • Se envía notificación mediante webhook de aceptación con la información completa:
      • Datos del prestador seleccionado
      • Información del técnico asignado
      • Detalles de la central que acepta el servicio
      • Tiempos estimados y costos acordados

  3. Asignar detalles (POST /api/v2/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 ​

La URL base de la API de TSALVA debe ser solicitada al área de TI de RobPixels.

Para obtener acceso a la API:

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

https://[URL_PROPORCIONADA_AREA_DE_TI]

Autenticación ​

Todos los endpoints requieren autenticación básica HTTP. Ver Autenticación para más detalles.

bash
Authorization: Basic <credenciales_base64>

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 ​

Servicios Directos ​

Consultas ​

Webhooks ​

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

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?

Consejo

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

Endpoints Principales ​

📍 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

Tsalva API - Documentación desarrollada por RobPixels

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