Configuración de los webhooks

Los webhooks son solicitudes iniciadas por Logístiko:

Logístiko → ERP

Información necesaria para la configuración

El cliente debe facilitar:

La URL pública del endpoint receptor.
Una clave de autorización, cuando se quiera validar el origen de las solicitudes.
Los webhooks que deben activarse.

URL del endpoint

El ERP debe proporcionar una URL accesible desde Internet que acepte solicitudes HTTP POST con contenido JSON.

Ejemplo:

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

Se recomienda utilizar exclusivamente HTTPS.

El endpoint debe aceptar las siguientes cabeceras:

Content-Type: application/json
Accept: application/json

Clave de autorización

La clave de autorización es opcional, aunque se recomienda utilizarla.

Cuando se configura, Logístiko envía el valor acordado en la cabecera HTTP Authorization.

Ejemplo:

Authorization: clave_acordada_con_el_cliente

El valor se envía exactamente como haya sido configurado.

Por tanto, si el ERP necesita utilizar el prefijo Bearer, debe proporcionarse el valor completo:

Authorization: Bearer clave_acordada_con_el_cliente

El endpoint receptor debe comparar el valor recibido con la clave configurada y rechazar las solicitudes no autorizadas.

Ejemplo de respuesta cuando la clave no es válida:

HTTP/1.1 401 Unauthorized

Selección de webhooks

No es obligatorio activar todos los webhooks disponibles.

Durante la puesta en marcha debe acordarse qué eventos necesita recibir el ERP según su operativa.

Por ejemplo, un ERP puede necesitar únicamente conocer:

Cuándo se despacha un servicio.
Cuándo se completa.
Cuándo se registra una incidencia.

En ese caso, no es necesario activar eventos relacionados con formularios, inicio de ruta o planificación previa.

Webhooks configurables

Webhook	Cuándo se envía	Consideraciones
Predespacho	Cuando existe una planificación previa al despacho	Opcional. Solo se utiliza cuando el ERP necesita información de la asignación para actualizar los servicios antes del despacho
Servicio asignado a ruta	Cuando la ruta se despacha y llega a la aplicación del conductor	Permite conocer la asignación definitiva del servicio
Ruta iniciada	Cuando el conductor inicia la ruta desde la aplicación	Opcional. No es necesario cuando el ERP solo necesita conocer el resultado final de los servicios
Llegada al destino	Cuando el conductor registra la llegada al punto de servicio	Pueden omitir este evento si no es relevante.
Servicio completado	Cuando el conductor finaliza correctamente el servicio	Normalmente utilizado para actualizar el estado final y recibir evidencias
Servicio con incidencia	Cuando el conductor registra una incidencia	Normalmente utilizado para conocer servicios no completados
Estado de servicio forzado	Cuando el estado se modifica excepcionalmente fuera del flujo normal	No debe ser habitual.
Formulario de inicio de ruta	Cuando el conductor completa el formulario configurado antes de iniciar la ruta	Opcional. Solo se envía si existe un formulario de inicio configurado
Formulario de fin de ruta	Cuando el conductor completa el formulario configurado al finalizar la ruta	Opcional. Solo se envía si existe un formulario de fin configurado

El webhook de predespacho no confirma que la ruta haya sido enviada al conductor. Comunica una planificación previa que todavía puede cambiar.

Eventos de inicio y fin de ruta

Los eventos relacionados con la ruta son opcionales.

El ERP no tiene que recibir necesariamente el webhook de ruta iniciada si únicamente necesita controlar el estado de las entregas o recogidas.

El formulario de inicio de ruta y el inicio efectivo de la ruta son eventos diferentes:

El conductor completa el formulario de inicio.
Logístiko puede enviar el webhook del formulario de inicio.
El conductor inicia la ruta.
Logístiko puede enviar el webhook de ruta iniciada.

Del mismo modo, el formulario de fin de ruta solo se comunica cuando:

Existe un formulario de fin configurado.
El conductor lo completa desde la aplicación.
El webhook correspondiente está activado para la integración.

La ausencia de estos eventos no impide recibir posteriormente los webhooks de llegada, servicio completado o incidencia.

Formularios dentro de los servicios

Los formularios asociados a una entrega o recogida también son opcionales.

Cuando un servicio tiene un formulario configurado y el conductor lo completa, sus respuestas pueden incluirse en el campo form del webhook.

Ejemplo:

{
  "uniqueId": "687000000000000000000001",
  "serviceRef": "ALB-001",
  "status": 4,
  "form": [
    {
      "label": "Estado del embalaje",
      "key": "estado_embalaje",
      "value": "Correcto",
      "valueType": 0,
      "valueTypeString": "text"
    }
  ]
}

El campo form puede no aparecer cuando:

El servicio no tiene ningún formulario configurado.
El formulario no aplica al evento recibido.
El conductor no ha completado el formulario.
La integración no tiene habilitado el envío de formularios.

Por tanto, el ERP debe considerar form como un campo opcional.

No debe rechazar el webhook cuando el campo no exista, sea null o esté vacío.

Las preguntas recibidas también dependen de la configuración realizada en Logístiko, por lo que el ERP no debe asumir que todos los servicios contendrán siempre las mismas preguntas.

Otros campos opcionales

Además de los formularios, algunos webhooks pueden incluir información opcional como:

Firma del destinatario.
Nombre y documento del firmante.
Fotografías.
Observaciones.
Coordenadas.
Artículos o bultos.
Información de cobro.
Motivos de incidencia.

La presencia de estos campos depende de:

La configuración de la empresa.
El tipo de evento.
Los datos registrados por el conductor.
Los formularios y evidencias exigidos en la aplicación.

El ERP debe aceptar que un mismo tipo de webhook pueda contener distintos campos opcionales.

Formato del payload

El formato de los webhooks se acuerda durante la puesta en marcha.

Logístiko puede enviar los eventos:

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

Objeto JSON

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

Array de objetos JSON

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

Cuando se configura el formato como array, incluso un evento con un único servicio se envía dentro de una lista.

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

Respuesta esperada

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

Por ejemplo:

Código	Significado
`200`	Evento recibido y procesado correctamente
`202`	Evento aceptado para procesamiento asíncrono
`204`	Evento recibido correctamente sin contenido de respuesta

Se recomienda:

Validar la autorización.
Validar y almacenar el payload.
Devolver rápidamente una respuesta 2xx.
Procesar internamente el evento de forma asíncrona.

Cualquier respuesta HTTP 300 o superior, error de conexión o tiempo de espera agotado se considera un envío fallido y puede provocar un reintento.

Información que debe confirmar el cliente

Antes de activar la integración debe confirmarse:

Documentación relacionada

Para consultar el funcionamiento general, formato de los payloads, política de reintentos, seguridad e idempotencia:

Configuración y funcionamiento de los webhooks

Documentación de los eventos disponibles: