Webhooks - Introducción

El sistema de webhooks de TSALVA tiene dos caras complementarias. Distinguirlas es clave para integrar correctamente:

• Entrante (tú llamas a TSALVA): el endpoint PUT /api/v3/aceptacion que un proveedor/central invoca para aceptar una oferta. Protegido por API key.
• Salientes (TSALVA te llama a ti): notificaciones PUT que TSALVA envía a la URL configurada en tu perfil de API cuando una central acepta tu oferta o cuando cambia el estado del servicio.

Fuente

Esta sección está documentada contra el código real de la API v3 (src/v3/...), no contra un contrato hipotético.

Mapa de webhooks

Webhook	Dirección	Método	Documentación
Aceptación de oferta (endpoint)	Entrante → TSALVA	PUT /api/v3/aceptacion	Ver
Notificación de aceptación	Saliente → tu servidor	PUT {url_api}{respuesta}	Ver
Cambio de estado	Saliente → tu servidor	PUT {url_api}{actualizar}	Ver

Webhooks salientes de un vistazo

Ambos webhooks salientes se envían por PUT, con Content-Type: application/json y, si tienes una apiKey registrada, el header x-apikey. La URL de destino se arma con tu url_api (URL base) más la ruta que corresponda del JSON api_endpoint. Consulta Configuración para el detalle.

🎯 Notificación de aceptación

Se envía cuando TSALVA elige la mejor oferta y quiere informarte qué central y técnico la tomaron. Payload real (resumen):

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "idGestor": "TSALVA",
  "dniGestor": "901668869",
  "dniPrestador": "900123456",
  "nombrePrestador": "Central Norte SAS",
  "identificadorTecnico": "12345678",
  "dniTecnico": "12345678",
  "telefonoTecnico": "+57 300-123-4567",
  "tarifaEstimadaServicio": "0",
  "tiempoLlegadaSitio": 25
}

Debes responder HTTP 200

Si no respondes 200 a la notificación de aceptación, TSALVA interpreta que rechazaste la asignación y libera el servicio. No hay reintentos.

🔄 Cambio de estado

Se envía en cada cambio de estado del servicio. codigoEstado viaja como cadena:

Código	Estado
3	En camino a origen
4	En sitio
5	Estado intermedio (tareas múltiples)
6	Incompleto
7	Cancelado
8	Finalizado

El código 0 no se notifica. Ver el payload completo en Cambio de Estado.

Flujo general

sequenceDiagram
    participant Cliente as Tu Aplicación
    participant TSALVA as TSALVA API
    participant Central

    Cliente->>TSALVA: 1. Crear oferta (POST /api/v3/oferta)
    TSALVA->>Central: 2. Distribuir oferta
    Central->>TSALVA: 3. Aceptar (PUT /api/v3/aceptacion)
    TSALVA->>Cliente: 4. Webhook aceptación (PUT)
    Cliente-->>TSALVA: HTTP 200 (confirma)
    Central->>TSALVA: 5. Técnico en camino / en sitio / finaliza
    TSALVA->>Cliente: 6. Webhook cambio de estado (PUT)
    Cliente-->>TSALVA: HTTP 200

Seguridad y confiabilidad (lo que hace el código)

• Verificación: el único mecanismo es el header x-apikey (opcional, según tu configuración). No hay firma HMAC del cuerpo.
• Reintentos: no existen. Cada webhook es un único intento.
• Timeout: no hay timeout explícito en el código; aplica el de axios por defecto. Responder rápido es una recomendación.
• Idempotencia y orden: no hay garantías de orden ni de entrega; diseña tu receptor para tolerarlo.

Consulta el detalle en Configuración.

Documentación de webhooks

Página	Contenido
Aceptación de oferta	Endpoint entrante PUT /api/v3/aceptacion + notificación saliente de aceptación
Cambio de estado	Notificación saliente de cambios de estado y códigos
Configuración	Cómo se arma la URL, seguridad, timeouts y reintentos reales

---

¿Necesitas ayuda?

El equipo de TSALVA puede apoyarte con la configuración inicial y pruebas de conectividad. Escribe a soporte@robpixels.com.

Importante

Tu endpoint debe estar accesible públicamente, aceptar PUT con application/json y responder 200. Recuerda: no hay reintentos.