> ## Documentation Index
> Fetch the complete documentation index at: https://docs.riqra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Preparación y entrega

> Avanzar el estado de preparación de un pedido y registrar la guía.

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`.

## 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`            |
| Cancelar                 | `POST /orders/{id}/cancel`                | `CANCELLED`            |

## Envío vs. recojo

El comportamiento depende del tipo de entrega del pedido (`shippingType`):

* **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.

```bash theme={null}
# 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`.

## Cancelar

`POST /orders/{id}/cancel` cancela un pedido que aún no fue despachado. Si el pedido ya está en
`FULFILLED` o más, responde `422` con `code` `CANNOT_CANCEL_DISPATCHED_ORDER`.