DocumentaciónAPI ReferenceFlujos de Órdenes

Flujos de Órdenes

Para poder operar con nuestras APIS es crucial que entiendas el flujo de un producto.

Estados de los item de una Orden

El flujo de procesamiento de órdenes incluye un total de 10 estados, de los cuales dos — ready_to_ship y cancel — pueden ser activados directamente por el seller. Estos estados existen a nivel de item y pueden ser consultados usando la API GetOrderItems. Para consultar el estado a nivel de orden completa, puedes usar la API GetOrder, donde el campo `status` devolverá un arreglo con todos los estados asociados a los ítems incluidos en la orden.

Estados de Compra

  • ●pending — Estado inicial donde se crea la orden. Se obtiene vía GetOrders o GetOrder, o desde la notificación webhook de creación de orden.
  • ●ready_to_ship — El seller confirma que está listo para enviar el producto. Desde este estado la orden no puede ser cancelada, y el stock reservado se deduce del stock disponible.
  • ●shipped — El seller entrega el paquete al operador logístico o logística de Falabella. Este estado se usa para medir el cumplimiento de primera milla del seller (OTS = On Time Seller).
  • ●delivered — El cliente ha recibido la orden. Este estado activa el pago al seller.
  • ●failed — Después de 3 intentos de entrega (puede variar según transportista), la orden no puede ser entregada y se marca como fallida.
  • ●canceled — Estado terminal. Puede ser activado por seller, cliente, agentes o proveedor logístico.

Estados Post-Venta

  • ●returned — Este estado se activa cuando Falabella recibe el producto que el cliente ha devuelto.

APIs del Flujo de Órdenes

  • ●GetOrders — Obtiene órdenes desde una fecha seleccionada, permitiendo filtros como estado. (Versión 2.0 disponible)
  • ●GetOrder — Obtiene los datos de una orden específica. (Versión 2.0 disponible)
  • ●GetOrderItems — Obtiene los items de una orden específica.
  • ●GetMultipleOrderItems — Obtiene items para un array de órdenes.
  • ●SetStatusToPackedByMarketplace — Marca un item como empacado. (Deprecated — info ahora disponible a través de GetOrderItems)
  • ●GetTrackingCode — Obtiene el código de seguimiento de envío. (Deprecated — info ahora disponible a través de GetOrderItems)
  • ●GetDocument — Obtiene una etiqueta de envío. El mimetype de respuesta será application/pdf o text/plain (ZPL).
  • ●SetStatusToReadyToShip — Marca un item como listo para envío.
  • ●SetInvoicePDF — Carga un documento tributario.
  • ●SetStatusToCanceled — Cancela la orden, solo si está en estado 'pending'.

Calculando el Valor Total de la Venta para Documentos Tributarios

1. Ten el OrderId para el cual quieres calcular el valor total. 2. Usa GetOrderItems o GetMultipleOrderItems para obtener los detalles de la orden. 3. El monto final ("Grand Total" en Seller Center) será la suma de los campos PaidPrice y ShippingAmount para cada producto en la orden. Es importante usar este cálculo como el método correcto para obtener el valor final de la venta. Si tu negocio tiene promociones especiales, el campo Price en GetOrder/GetOrders podría diferir, causando posibles problemas con la generación de documentos tributarios.

¿Cómo Saber si se ha Realizado una Venta o Cambio de Estado?

Existen dos métodos (idealmente usados complementariamente): • Usando Webhook: Configura los eventos de órdenes, para que cada vez que se realice una venta seas notificado en la URL indicada. Usa GetOrders después para registrar los datos de la orden. • Usando la API GetOrders: Crea un cron job que consulte la API a intervalos regulares, aplicando filtros de estado para obtener órdenes con estado 'Pending'. Almacena datos clave como el OrderID. También puedes filtrar por otros estados (Pending, Ready_To_Ship, Shipped, Delivered, Failed, Canceled).

Flujo Fulfillment by Seller

  • ●1. Una vez registrada la nueva venta y almacenados los datos de la orden, usa GetOrderItems para obtener los items. Para lotes, usa GetMultipleOrderItems. Esto proporciona OrderItemIds, PackageId y TrackingCode. Reintenta si los campos aún no están disponibles.
  • ●2. Genera la etiqueta de envío usando GetDocument.
  • ●3. Marca el producto como listo para recolección usando SetStatusToReadyToShip. Respeta el tiempo de envío prometido (PromisedShippingTime).
  • ●4. Carga el documento tributario correspondiente usando SetInvoicePDF.

Fulfillment by Falabella (FBF)

Las órdenes FBF se identifican por ShippingType = 'Own Warehouse'. Es crucial reconocer estas órdenes para evitar reducir el inventario de tu propia bodega, ya que el inventario FBF se almacena en las bodegas de Falabella. • Usa GetOrder, GetOrderItems, o GetMultipleOrderItems para detalles de la orden. • Rastrea la evolución de estados usando GetOrders. • NO apliques SetStatusToReadyToShip. • Puedes subir facturas usando SetInvoicePDF.

Flujo en Modalidad Directo

Los cambios de estado disponibles vía API para el modelo Fulfillment by Seller son los mismos que se utilizan en el modelo de envío directo. Cualquier otro estado fuera de estos debe ser gestionado exclusivamente a través del aplicativo habilitado para ejecutar el flujo correspondiente.

Seguimiento de Estados

Se puede hacer seguimiento de la evolución de los estados activando el evento onOrderItemsStatusChanged del webhook o bien mediante el uso del API GetOrders.

¿Cómo Puedo Cancelar una Orden?

Las órdenes solo pueden ser canceladas en el estado pending. Tanto el cliente como el seller pueden cancelar el producto. Si la cancelación es realizada por el seller, se aplicará una penalización.

Flujo de Órdenes

Puedes hacer clic en la imagen para poder visualizarla o puedes descargar haciendo clic en el botón derecho de mouse y seleccionando guardar cómo, para tener la imagen en su resolución original.

Flujos de ProductosGestión de Stock en Múltiples Bodegas