🔔 5 - Seguimiento, Webhooks y Evidencias del Envío

Seguimiento, Webhooks y Evidencias del Envío

Esta guía reúne las herramientas disponibles para realizar seguimiento a un envío, recibir notificaciones automáticas mediante Webhooks, obtener evidencias como firma o fotos del proceso de entrega, y probar toda la experiencia en el entorno de testing.

1. Seguimiento del estado de un envío / Polling

Como alternativa o respaldo a los webhooks, podés consultar manualmente el estado de un envío usando el siguiente endpoint

Endpoint:

GET /shippings/{shippingId}?appId=<tu-app-id>

Este endpoint devuelve todos los datos del envío y su historial de estados. Importante: el parámetro shippingId debe ser el ID completo devuelto en la creación del envío. No se puede usar internalCode ni una versión recortada.

Ejemplo de llamada real:

GET https://api-prod.moova.io/b2b/shippings/9a680-37a8-11f0-b703-07e261b?appId=847-11e-b844-f5a05000e00

Respuesta esperada (simplificado):

{
   "id":"9840a680-37a8-11f0-b703-07ea07d2261b",
   "type":"pickup",
   "status":"DELIVERED",
   "from":{
      "..."
   },
   "to":{
      "..."
   },
   "statusHistory":[
      {
         "status":"DRAFT",
         "createdAt":"..."
      },
      {
         "status":"READY",
         "createdAt":"..."
      },
   ]
}

Seguimiento de multiples envios

Puedes obtener un array de envios usando el siguiente endpoint

Endpoint:

GET /shippings/{shippingId}?appId=<tu-app-id>

2. Webhooks: recibir eventos en tiempo real

Los Webhooks se configuran desde https://dev.moova.io/company/api en el ambinete de test, y en produccion: https://dashboard.moova.io/company/api o . Allí podrás:

Copiar tu appId
Regenerar la API Key
Configurar webhook URL, método y headers opcionales

Estructura del Webhook

Los Webhooks también pueden incluir el campo pickedUpShippings. Este campo solo se devuelve cuando el shippingType es del tipo pickup o reversed, y contiene un array con todos los envíos que fueron recolectados:

En el caso de pickup, se refiere a los envíos que fueron retirados desde el warehouse del vendedor hacia el warehouse de Moova. Esto permite saber qué pedidos están actualmente en ruta hacia el depósito.
En el caso de reversed, se refiere a los pedidos almacenados en el warehouse de Moova que están siendo devueltos al seller.
En ambiente de prueba, las imágenes se devuelven en formato GIF. En producción, las evidencias pueden estar en formato GIF, JPG o PNG. Siempre se entrega como una URL accesible públicamente

Importante: Las fotos y la informacion de los envios se conservan durante 24 meses.

Moova enviará los cambios de estado en formato JSON, con campos como status, createdAt y details. Ejemplo:

{
   "id":"9eeaa9-b35b-453e-97af-6a680b4669e5",
   "status":"INTRANSIT",
   "shippingType":"next_day",
   "details":{
      "courierPosition":{
         "lat":"-12.21176190",
         "lng":"-76.96016480"
      }
   },
   "createdAt":"2025-05-23 08:18:47"
}

Evidencia de entrega

También puede recibirse un Webhook cuando se carga una imagen o firma en el sistema, con evento:

{
   "event":"ShippingPhotoWasCreated",
   "date":"2025-05-23 08:19:17",
   "details":{
      "type":"SIGNATURE",
      "full_path":"https://s3.amazonaws.com/prod.files.moova.io/...jpg"
   }
}

Este tipo de webhook es más útil para las integraciones del tipo SaaS

Test

Puedes testear los hooks desde b2b-api.moova.io en donde puedes replicar el flujo de cambio de estados como lo haria un courier

3. Evidencias de entrega

Una vez entregado un envío, se puede obtener evidencia (foto, firma o comentario) mediante el siguiente endpoint:

GET /evidence/{shippingId}

Ejemplo de respuesta:

{   "signatureUrl": "https://s3.amazonaws.com/moova/signed/12345.jpg",   "photoUrl": "https://s3.amazonaws.com/moova/pictures/12345.jpg",   "comment": "Entregado sin novedades." }

3. Estados cancelados y razones

Estado	Código	Descripción
CANCELED	out_of_area	Fuera del Área
CANCELED	dangerous_area	Área Peligrosa
CANCELED	unrecognized_address	Dirección no Reconocida
CANCELED	lost_package	Paquete perdido
CANCELED	destroyed	Paquete destruido
CANCELED	fraud_risk	Detectado como fraude
CANCELED	created_by_mistake	Creado por error
CANCELED	other	Otra razón

4. Tipos de incidencia posibles

Código	Descripción
error	Tomado por error
technical_issue	Problema con el vehículo
absent_client	Cliente ausente
incorrect_address	Dirección incorrecta
unavailable_product	Producto no disponible
unrecognized	El cliente no reconoce el envío
wrong_size	El tamaño del paquete es distinto
rejected	Envío no esperado
cancelation	El cliente canceló el envío
missing_security_code	No posee el código de seguridad correcto
cannot_scan_info	No se pudo escanear la identificación
fraud_risk	Sospecha de fraude

5. Reintentos

Si el servidor receptor responde con un código diferente a 200 o 201, Moova intentará reenviar la notificación hasta 7 veces, con un intervalo de 10 minutos entre cada intento.

En caso de no obtener una respuesta satisfactoria luego del séptimo intento, el webhook será desactivado automáticamente.

Desde el panel de administración o vía API, es posible forzar el reenvío de las notificaciones que no hayan sido entregadas correctamente.

IMPORTANTE: Siempre deben responder con un código 200 o 201, incluso si el webhook recibido no tiene el formato esperado o si ocurre un error interno en su sistema.
De lo contrario, Moova reintentará enviar la notificación hasta 7 veces y, si no obtiene una respuesta exitosa, el webhook será desactivado automáticamente.