Configuración y funcionamiento de los webhooks

Dirección de las comunicaciones

Los webhooks son solicitudes iniciadas por Logístiko:

Logístiko → ERP

El ERP o sistema receptor debe proporcionar una URL accesible que acepte solicitudes HTTP POST con contenido JSON.

Configuración del endpoint

El cliente debe facilitar:

• La URL del endpoint receptor.
• La clave de seguridad que Logístiko enviará en la cabecera HTTP Authorization, cuando se haya configurado autenticación. (opcional)

Ejemplo de endpoint:

https://erp.example.com/integrations/logistiko/webhooks

Ejemplo de cabeceras enviadas por Logístiko:

Authorization: {clave_configurada}
Content-Type: application/json
Accept: application/json

El valor de la cabecera Authorization se acordará durante la configuración de la integración.

La autenticación mediante esta cabecera es opcional, aunque se recomienda utilizarla para validar que las comunicaciones proceden de Logístiko.

Formato del payload

El formato de los webhooks se configura durante la puesta en marcha de la integración.

Logístiko puede enviar los eventos:

• Como un objeto JSON.
• Como un array de objetos JSON.

Envío como objeto

{
  "uniqueId": "687000000000000000000001",
  "serviceRef": "ALB-001",
  "status": 4
}

Envío como array

[
  {
    "uniqueId": "687000000000000000000001",
    "serviceRef": "ALB-001",
    "status": 4
  }
]

Cuando se configura el envío como array, incluso los eventos que contienen un único elemento se envían dentro de una lista.

El webhook de predespacho se envía siempre como un array, ya que puede incluir varios servicios pertenecientes a una misma planificación.

Ejemplo de predespacho:

[
  {
    "uniqueId": "687000000000000000000001",
    "serviceRef": "ALB-001",
    "routeRef": "RUTA-15",
    "driverCode": "CONDUCTOR-01",
    "status": 40
  },
  {
    "uniqueId": "687000000000000000000002",
    "serviceRef": "ALB-002",
    "routeRef": "RUTA-15",
    "driverCode": "CONDUCTOR-01",
    "status": 40
  }
]

El sistema receptor debe confirmar durante la puesta en marcha qué formato utilizará.

Se recomienda mantener el mismo formato en todos los entornos de la integración.

Respuesta esperada

El endpoint receptor debe devolver un código HTTP 2xx cuando el evento haya sido recibido correctamente.

Por ejemplo:

Cualquier respuesta HTTP 300 o superior se considera un envío no satisfactorio y puede provocar un reintento.

También se considera fallido el envío cuando:

• No se puede establecer la conexión.
• El endpoint no responde dentro del tiempo máximo.
• Se produce un error durante la comunicación.
• Se produce un error al leer la respuesta.

El contenido de la respuesta no necesita incluir información adicional, salvo que se acuerde expresamente durante la integración.

Procesamiento asíncrono

Se recomienda responder lo antes posible.

Cuando el tratamiento del evento pueda tardar varios segundos, el sistema receptor debería:

1. Validar la autenticación.
2. Validar el formato del payload.
3. Almacenar o encolar el evento.
4. Devolver una respuesta HTTP 2xx.
5. Procesar internamente la información de forma asíncrona.

De esta forma se evita que Logístiko considere fallida la comunicación debido a un tiempo de respuesta elevado.

Identificación de servicios y rutas

El sistema receptor debe utilizar los identificadores incluidos en el payload para relacionar el evento con el servicio o la ruta correspondiente.

Dependiendo del evento, pueden recibirse campos como:

Se recomienda utilizar uniqueId como identificador principal para relacionar el servicio recibido con el registro correspondiente en el ERP.

Para eventos relacionados con rutas pueden utilizarse routeId y routeRef.

Idempotencia y eventos duplicados

El sistema receptor debe estar preparado para recibir más de una vez el mismo evento.

Esto puede ocurrir, por ejemplo, cuando:

• El endpoint devuelve un error.
• Se supera el tiempo máximo de respuesta.
• Logístiko no puede confirmar si el evento fue procesado correctamente.
• Se ejecuta un reintento automático.
• Se ejecuta el proceso posterior de recuperación de errores.

La recepción repetida de un evento no debe provocar:

• La creación duplicada de documentos.
• La duplicación de entregas.
• La duplicación de incidencias.
• El registro repetido del mismo cambio de estado.
• Actualizaciones inconsistentes.
• El cobro duplicado de un importe.

El campo uniqueId identifica el servicio, pero no representa necesariamente un identificador único de cada intento de webhook.

Para evitar duplicados, el sistema receptor puede utilizar una combinación de campos como:

• uniqueId
• status
• timestamp
• routeId
• serviceId

Ejemplo de clave de idempotencia creada por el receptor:

{uniqueId}-{status}-{timestamp}

También puede comprobarse el estado actual del servicio antes de aplicar una actualización.

Fechas y horas

Las fechas incluidas en los webhooks se envían habitualmente en formato epoch milisegundos.

Ejemplo:

{
  "timestamp": 1784535600000,
  "dateArrive": 1784536200000,
  "dateDeparture": 1784536800000
}

El sistema receptor debe convertir estos valores a la zona horaria que corresponda a su operativa.

No debe interpretarse el valor como epoch en segundos.

Política de reintentos

Logístiko considera que un webhook se ha enviado correctamente cuando el endpoint receptor devuelve un código HTTP comprendido entre 200 y 299.

El envío se considera fallido cuando:

• El receptor devuelve un código HTTP 300 o superior.
• No se puede establecer la conexión.
• Se supera el tiempo máximo de conexión.
• Se supera el tiempo máximo de lectura.
• Se produce una excepción durante el envío.

Intentos ordinarios

La política estándar contempla:

1. Un primer intento de envío.
2. Un reintento ordinario si el primer intento no se completa correctamente.

El primer intento puede procesarse a partir de los 30 segundos desde la generación del evento.

Si el primer intento falla, el siguiente intento puede procesarse a partir de los 3 minutos desde el intento anterior.

Estos tiempos son intervalos mínimos.

El envío real puede producirse algunos segundos después debido a:

• La frecuencia de procesamiento de la cola.
• El número de eventos pendientes.
• La carga del sistema.
• El número de comunicaciones de la empresa.

Frecuencia de procesamiento

La cola estándar de webhooks se revisa aproximadamente cada minuto.

Por tanto, un evento que ya cumple el tiempo mínimo de envío será procesado en uno de los siguientes ciclos disponibles.

Tiempo máximo de respuesta

El tiempo máximo de conexión y lectura depende del número de servicios incluidos en la comunicación.

Como referencia, los tiempos configurados inicialmente pueden variar aproximadamente entre 5 y 10 segundos.

Cuando se produce un timeout y la comunicación se reintenta, el tiempo máximo puede aumentar progresivamente.

El tiempo máximo de espera está limitado a 20 segundos.

Por este motivo, se recomienda que el endpoint receptor devuelva una respuesta 2xx rápidamente y procese el evento de forma asíncrona.

Periodo ordinario de procesamiento

Los eventos pendientes forman parte del ciclo ordinario de envío durante las primeras 24 horas desde su creación.

Una vez superado este periodo, los eventos dejan de formar parte del ciclo ordinario de reintentos.

Recuperación de errores

Logístiko dispone adicionalmente de un proceso de recuperación para determinados eventos que han finalizado con error.

Este proceso:

• Se ejecuta durante una ventana nocturna.
• Puede revisar errores producidos durante los últimos 3 días.
• Solo selecciona eventos creados hace más de una hora.
• Solo selecciona eventos cuyo último intento se realizó hace más de una hora.
• Se ejecuta como máximo una vez cada 2 horas dentro de la ventana nocturna.

El proceso de recuperación no garantiza que todos los eventos vuelvan a enviarse, ya que depende del estado en el que haya quedado cada comunicación.

Importante: el sistema receptor no debe depender de un número ilimitado de reintentos. Debe supervisar la disponibilidad de su endpoint y comunicar cualquier interrupción prolongada.

Orden de los eventos

El sistema receptor no debe asumir que todos los eventos se recibirán necesariamente en el mismo orden en el que se produjeron.

Un evento anterior puede llegar después que otro más reciente debido a:

• Reintentos.
• Errores temporales.
• Diferencias en el tiempo de procesamiento.
• Comunicaciones agrupadas.
• Procesamiento asíncrono.

Antes de actualizar el estado del ERP se recomienda comprobar:

• El estado actual del servicio.
• El valor de status.
• El valor de timestamp.
• Las fechas específicas del evento.
• El identificador de ruta.
• El identificador del servicio.

No debería reemplazarse un estado más reciente por otro anterior únicamente por el orden de recepción de las comunicaciones.

Seguridad

Se recomienda:

• Utilizar exclusivamente URLs HTTPS.
• Validar que el método recibido sea POST.
• Validar que el encabezado Content-Type sea application/json.
• Validar el valor recibido en la cabecera Authorization.
• Rechazar solicitudes con una clave incorrecta.
• Validar la estructura del payload.

Ejemplo de validación:

Authorization recibida == clave configurada

Si la clave no coincide, el endpoint debería devolver:

HTTP/1.1 401 Unauthorized

Fotografías y firmas

Algunos eventos de finalización o incidencia pueden incluir evidencias de entrega.

Por ejemplo:

• Firma.
• Nombre del firmante.
• Documento identificativo.
• Fotografía.
• Lista de fotografías.

Las imágenes y firmas pueden enviarse en Base64 utilizando una URI de datos:

data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...

Campos relacionados:

El sistema receptor debe tener en cuenta que los payloads con imágenes pueden tener un tamaño considerable.

Se recomienda:

• Configurar un tamaño máximo suficiente en el servidor.
• No registrar el Base64 completo en logs.
• Decodificar y almacenar las imágenes de forma segura.
• Validar el tipo MIME antes de guardar el archivo.

Formularios

Algunos webhooks pueden incluir las respuestas de formularios cumplimentados por el conductor.

Las respuestas se incluyen dentro de form.

Ejemplo:

{
  "form": [
    {
      "label": "Kilómetros del vehículo",
      "key": "kilometros",
      "value": 125430,
      "valueType": 1,
      "valueTypeString": "number"
    },
    {
      "label": "¿Existen daños?",
      "key": "danos",
      "value": false,
      "valueType": 2,
      "valueTypeString": "boolean"
    }
  ]
}

Los tipos habituales son:

Los campos exactos del formulario dependen de la configuración realizada en Logístiko.

Eventos disponibles

Logístiko puede comunicar eventos relacionados con:

• Predespacho y planificación de rutas.
• Asignación de servicios a una ruta.
• Inicio de ruta.
• Llegada al destino.
• Finalización o entrega de servicios.
• Servicios con incidencia.
• Formularios de inicio de ruta.
• Formularios de fin de ruta.

Los eventos concretos, la URL receptora, el formato del payload y la autenticación se configurarán durante la puesta en marcha de cada integración.

Checklist del endpoint receptor

Antes de activar los webhooks en producción debe comprobarse:

• El endpoint utiliza HTTPS.

• El endpoint acepta solicitudes POST.

• El endpoint acepta application/json.

• La URL es accesible desde Logístiko.

• La cabecera Authorization se valida correctamente.

• El endpoint admite el formato de objeto o array acordado.

• El endpoint admite el webhook de predespacho como array.

• El endpoint responde con un código 2xx.

• El tiempo de respuesta es inferior al timeout configurado.

• Las fechas epoch se interpretan como milisegundos.

• El servidor admite el tamaño de las fotografías y firmas.