Preparación y entrega - Riqra

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:

UNFULFILLED → IN_PROGRESS → FULFILLED → DELIVERED

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.

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

Acción	Endpoint	Lleva a
Iniciar preparación	`POST /orders/{id}/fulfillment/start`	`IN_PROGRESS`
Despachar / marcar listo	`POST /orders/{id}/fulfillment/fulfill`	`FULFILLED`
Actualizar guía	`PATCH /orders/{id}/fulfillment/tracking`	(sin cambio de estado)
Marcar entregado	`POST /orders/{id}/fulfillment/deliver`	`DELIVERED`

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 (PICKUP): no lleva guía. Envía un cuerpo vacío.

# Despachar un pedido de envío con guía
curl -X POST "https://api-v2.riqra.com/public/v1/orders/0b2e9f5a-1c3d-4e6f-8a9b-0c1d2e3f4a5b/fulfillment/fulfill" \
  -H "Authorization: Bearer rq_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "carrier": "Olva", "trackingNumber": "OL123456", "trackingUrl": "https://track.olva.pe/OL123456" }'

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.