Actualizar estado

Webhook para que los carriers notifiquen a Falabella, en tiempo real, los cambios de estado de un paquete.

POSTActualizar estado

curl --location 'https://logistic-api-qa.falabella.com/schn-trmg-3pl-directo/v1/webhook/directo' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--header 'x-country: CL' \
--header 'x-environment: UAT' \
--data '{
  "updates": [
    {
      "lpn": "300123456789123",
      "carrier": "enviosexpress",
      "carrierAggregator": "envios SPA",
      "latitude": 1.2312,
      "longitude": -1.321,
      "statuses": [
        {
          "statusCode": "DELIVERED_001",
          "statusDate": "2026-02-18T15:45:00Z",
          "description": "Entregado exitosamente en domicilio.",
          "deliveryProof": {
            "recipientName": "John Doe",
            "recipientId": "11111111-1",
            "images": ["https://storage-url.io/pod-0.jpg"]
          }
        }
      ]
    }
  ]
}'

Este endpoint, que funciona como un webhook, permite a los operadores logísticos (carriers) notificar a Falabella en tiempo real sobre los cambios de estado de un paquete.

URL del endpoint

●Ambiente QA: https://logistic-api-qa.falabella.com/schn-trmg-3pl-directo/v1/webhook/directo
●Ambiente Producción: https://logistic-api-prod.falabella.com/schn-trmg-3pl-directo/v1/webhook/directo

Reglas Clave

Flujo exitoso de entrega - IN_TRANSIT → DELIVERED El evento DELIVERED debe incluir: - 2 imágenes de evidencia: • 1 imagen del paquete entregado. • 1 imagen de la fachada o dirección de entrega. - Geolocalización de la entrega. Flujo fallido de entrega - IN_TRANSIT → DELIVERY_ATTEMPTED → UNDELIVERED Antes de reportar UNDELIVERED, se deben enviar los estados intermedios correspondientes. Toda orden que no pueda ser entregada debe finalizar con el estado UNDELIVERED. Una vez reportado UNDELIVERED, la orden será cancelada automáticamente. Regla de intentos de entrega Tras dos intentos de entrega fallidos, la orden será cancelada automáticamente por el sistema. No obstante, se recomienda igualmente reportar el estado UNDELIVERED para asegurar la correcta trazabilidad del proceso, cubrir eventuales fallas en la cancelación automática y garantizar la consistencia de los reportes operacionales. Consideraciones importantes DELIVERED y UNDELIVERED son estados finales. No se permiten transiciones posteriores una vez alcanzado cualquiera de estos estados.

Headers

Campo	Tipo	Requerido	Descripción
Content-Type	`string`	Sí	Debe ser `application/json`.
Authorization	`string`	Sí	Token Bearer, obtenido a través del endpoint de Autenticación Operador Logístico.
x-country	`string`	Sí	Código de país. Actualmente soportado: CL.
x-environment	`string`	Sí	Ambiente. Valores válidos: UAT, PROD.

Request Body

A continuación se detalla la estructura del objeto JSON esperado.

Campo	Tipo	Requerido	Descripción
updates	`array`	Sí	Lista de actualizaciones. Debe contener al menos un elemento.
↳ lpn (`trackingId`)	`string`	Sí	Identificador único del paquete.
↳ carrier	`string`	Sí	Nombre del carrier que reporta el estado.
↳ carrierAggregator	`string`	No	Nombre del agregador de carriers, si aplica.
↳ latitude	`number`	Sí	Latitud de la ubicación donde se registra el evento.
↳ longitude	`number`	Sí	Longitud de la ubicación donde se registra el evento.
↳ statuses	`array`	Sí	Lista de estados a reportar para el paquete.
↳ statusCode	`string`	Sí	Código oficial del estado, según el catálogo estandarizado de Falabella.
↳ statusDate	`string`	Sí	Fecha y hora del evento en formato `ISO 8601 UTC`.
↳ description	`string`	Sí	Descripción textual del evento ocurrido.
↳ deliveryProof	`object`	Sí*	Evidencia de entrega (POD). *Obligatorio si el `statusCode` es de categoría `DELIVERED`.
↳ recipientName	`string`	Sí	Nombre del receptor.
↳ recipientId	`string`	Sí	Documento de identificación del receptor.
↳ images	`array`	Sí	Arreglo de URLs (máximo 5) con las fotografías de la evidencia. Las URLs deben estar en una whitelist configurada previamente.
↳ additionalData	`array`	No	Lista de hasta 10 pares `key`/`value` con datos adicionales opcionales.

Catálogo de StatusCode (Falabella)

Los valores para el campo statusCode son estrictamente los definidos en esta tabla. La API rechazará cualquier código que no esté en esta lista.

Categoría	Código	Descripción
Delivery Attempted	`DELIVERY_ATTEMPTED_001`	Se intentó la entrega al menos una vez pero el paquete no pudo ser entregado.
Delivery Attempted	`DELIVERY_ATTEMPTED_002`	El intento de entrega falló por indisponibilidad del destinatario.
Delivery Attempted	`DELIVERY_ATTEMPTED_003`	Múltiples intentos de entrega fallidos.
Undelivered	`UNDELIVERED_001`	El paquete no fue entregado.
Undelivered	`UNDELIVERED_006`	El paquete fue dañado.
In Transit	`IN_TRANSIT_001`	Paquete moviéndose por la red del carrier.
In Transit	`IN_TRANSIT_002`	Paquete en instalación de origen.
In Transit	`IN_TRANSIT_003`	Paquete recogido por el carrier.
In Transit	`IN_TRANSIT_005`	Paquete en hub intermedio.
In Transit	`IN_TRANSIT_006`	Paquete en transporte de larga distancia.
Out for Delivery	`OUT_FOR_DELIVERY_001`	Paquete en reparto.
Delivered	`DELIVERED_001`	Entregado al destinatario.
Delivered	`DELIVERED_002`	Retirado en sucursal.
Available for Pickup	`AVAILABLE_FOR_PICKUP_001`	Listo para retiro.
Received	`RECEIVED_001`	Recibido por proceso interno.
Exception	`EXCEPTION_001`	Problema de dirección o destinatario.
Exception	`EXCEPTION_002`	Destinatario rechazó el envío.
Exception	`EXCEPTION_004`	Retraso por fuerza mayor.
Exception	`EXCEPTION_005`	Retenido por el carrier.
Exception	`EXCEPTION_007`	Paquete perdido.
Exception	`EXCEPTION_008`	Retraso operacional.
Exception	`EXCEPTION_010`	Excepción interna de automatización.
Exception	`EXCEPTION_012`	Presunto extravío.
Exception	`EXCEPTION_013`	Fuera de cobertura.
Exception	`EXCEPTION_014`	Destinatario desconocido.
Expired	`EXPIRED_001`	Paquete expirado.

Respuesta 200

{
  "success": true,
  "processedCount": 1,
  "failedCount": 0
}

Código	Mensaje
400	Validation failed: error en la validación del esquema enviado en el payload (ej. campo requerido faltante o tipo de dato incorrecto).
500	Failed to process status update: error interno del servidor al intentar procesar la actualización de estado.

Obtener orden por LPN