Skip to main content
Estos endpoints avanzan la preparación de un pedido y registran la guía de seguimiento. Todos requieren el scope fulfillment:write y devuelven el pedido actualizado.

​
Estados

La preparación avanza en un solo sentido por esta escalera:
  • Solo avanza, nunca retrocede.
  • Se permiten saltos (por ejemplo de UNFULFILLED directo a FULFILLED).
  • Un avance inválido responde 422 con code INVALID_FULFILLMENT_TRANSITION.
  • Un pedido en AWAITING_REVIEW no se puede preparar: cualquier avance responde 409 con code ORDER_AWAITING_REVIEW hasta que el comercio lo apruebe y pase a PLACED.
El estado vive en fulfillmentStatus, en la raíz del pedido. El despacho en sí — transportista, guía y fechas — viaja en fulfillments, vacío mientras el pedido siga UNFULFILLED. Hoy un pedido se prepara y despacha en un solo envío, así que la lista nunca trae más de un elemento.

​
Endpoints

​
Envío vs. recojo

El comportamiento depende del tipo de entrega del pedido (shippingMethod.type):
  • Envío (DELIVERY): puedes incluir la guía (carrier, trackingNumber, trackingUrl) al despachar o entregar.
  • Recojo en agencia (COURIER_PICKUP): el pedido viaja hasta una agencia del courier (courierBranch) donde el comprador lo recoge. Admite guía igual que un envío.
  • Recojo (PICKUP): no lleva guía. Envía un cuerpo vacío.
Si la organización registró sus couriers, puedes enviar courierId en lugar de (o además de) carrier: el pedido queda asignado a ese courier, carrier toma su nombre y trackingUrl se deriva de su plantilla de seguimiento cuando la tiene. Si el comprador eligió el courier en el checkout, el pedido lo conserva: un courierId o un carrier distinto devuelve 422 con el código ROUTE_COURIER_LOCKED. shippingMethod.payment indica quién paga el flete: PREPAID (cobrado en el checkout) o COLLECT (flete por pagar al courier).

​
Actualizar la guía

PATCH /orders/{id}/fulfillment/tracking sobrescribe la guía de un pedido de envío ya despachado (FULFILLED). Requiere carrier y trackingNumber. Sobre un pedido que no es de envío responde 422 con code ORDER_NOT_SHIPPABLE.