ReferenciaAPI LogísticaActualizar estado
POST
Actualizar estado
Webhook para que los carriers notifiquen a Falabella, en tiempo real, los cambios de estado de un paquete.
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.falabella.com/schn-trmg-3pl-directo/v1/webhook/directo`
Headers
x-country
string
RequeridoCódigo del país (ej.
CL).x-environment
string
RequeridoEntorno de ejecución (ej.
UAT).Authorization
string
RequeridoToken Bearer de autenticación.
Content-Type
string
RequeridoFormato del body. Debe ser
application/json.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. |