> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.sellercenter.pe/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.sellercenter.pe/_mcp/server.

# Órdenes

Consulta de órdenes y avance de su ciclo de vida.

* Consultas y cambios de estado usan la URL de Seller Center.
* **Subir comprobante de pago** usa la URL del gateway (requiere `apiKey`).

### Flujo de una orden

Lo que haces depende de tu **modalidad de despacho**. Cada seller tiene **una sola** modalidad, acordada con Intercorp Retail; la orden no trae un campo que la indique.

| Modalidad                         | Quién lleva el pedido                                         | Hasta dónde actualizas el estado                                                     |
| --------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| **Despacho por Intercorp Retail** | Empacas el pedido e Intercorp Retail lo recoge en tu almacén. | Hasta `invoiced` (*Enviada*). Los estados siguientes los actualiza Intercorp Retail. |
| **Despacho propio**               | Tú entregas el pedido en el domicilio del cliente.            | Hasta `delivered` (*Entregada*).                                                     |

> **Confirma tu modalidad antes de integrar el paso 4.** Solo lo usan los sellers con **despacho propio**. Si tu modalidad es despacho por Intercorp Retail, no lo ejecutes: actualizar ese estado le corresponde a Intercorp Retail. Si no estás seguro de tu modalidad, consúltala con tu contacto de Intercorp Retail antes de integrar.

```
Llega una orden pagada (webhook ORDER_READY_FOR_HANDLING)
                  │
                  ▼
        ┌────────────────────┐
        │ ready-for-handling │
        └────────────────────┘
                  │  1. Iniciar manejo
                  ▼
        ┌────────────────────┐
        │      handling      │
        └────────────────────┘
                  │  2. Facturar y despachar
                  ▼
        ┌────────────────────┐
        │      invoiced      │ ◀── 3. Subir comprobante de pago (no cambia el estado)
        └────────────────────┘
                  ├──▶ Despacho por Intercorp Retail: tu parte termina aquí
                  │
                  │  ── Desde aquí, solo despacho propio ──
                  │  4. Confirmar entrega
                  ▼
        ┌────────────────────┐
        │     delivered      │ ──▶ Despacho propio: termina aquí
        └────────────────────┘
```

| Paso | Cuándo                                                                               | Request                          | Estado antes → después            | Webhook que recibirás |
| ---- | ------------------------------------------------------------------------------------ | -------------------------------- | --------------------------------- | --------------------- |
| 1    | Aceptas la orden y empiezas a prepararla                                             | **1. Iniciar manejo**            | `ready-for-handling` → `handling` | `ORDER_HANDLING`      |
| 2    | Facturas y despachas el pedido (o lo dejas listo para el recojo de Intercorp Retail) | **2. Facturar y despachar**      | `handling` → `invoiced`           | `ORDER_INVOICE`       |
| 3    | Adjuntas la boleta o factura emitida al cliente                                      | **3. Subir comprobante de pago** | `invoiced` (no cambia)            | —                     |
| 4    | *Solo despacho propio:* el cliente recibió el pedido                                 | **4. Confirmar entrega**         | `invoiced` → `delivered`          | `ORDER_DELIVERY`      |

**Resumen:**

* **Despacho por Intercorp Retail:** 1 → 2 → 3. Recibirás los webhooks de los estados siguientes.
* **Despacho propio:** 1 → 2 → 3 → 4.

### Datos del cliente y dirección de despacho

En **Detalle de orden**, el teléfono (`clientProfileData.phone`) y la dirección (`shippingData.address`, salvo `receiverName`) vienen enmascarados (`**********`). Los datos completos llegan en el webhook **`ORDER_READY_FOR_HANDLING`** (ver [Webhooks](/guias/webhooks)): guárdalos al recibirlo.

### Todos los estados (`status`)

| Código                | Nombre en Seller Center | Significado                                                                           |
| --------------------- | ----------------------- | ------------------------------------------------------------------------------------- |
| `payment-pending`     | No pagada               | El cliente aún no paga. **No atender.**                                               |
| `ready-for-handling`  | Para manejo             | Pagada; debes iniciar el manejo.                                                      |
| `handling`            | Para envío              | En preparación; debes facturar y despachar.                                           |
| `partially-invoiced`  | Envío incompleto        | Se despachó solo parte de los items.                                                  |
| `invoiced`            | Enviada                 | Facturada y despachada.                                                               |
| `partially-delivered` | Parcialmente entregada  | Se entregó solo parte de los items.                                                   |
| `delivered`           | Entregada               | Entregada al cliente.                                                                 |
| `pending-withdrawal`  | Pendiente de retiro     | Retiro en tienda: lista para que el cliente la recoja. Lo actualiza Intercorp Retail. |
| `retired`             | Retirado                | Retiro en tienda: el cliente la recogió. Lo actualiza Intercorp Retail.               |
| `canceled`            | Cancelada               | **No atender.**                                                                       |
| `in-annulment`        | En anulación            | Solicitud de anulación en curso.                                                      |
| `in-return`           | En devolución           | Solicitud de devolución en curso.                                                     |
| `returned`            | Devuelta                | Devolución completada.                                                                |

### Errores al cambiar de estado

| Respuesta                                                         | Causa                                                                                                      |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `400` `{"message": null}` o `{"message": "Invalid order status"}` | La orden no está en el estado requerido para ese paso. Consulta el **Detalle de orden** y revisa `status`. |
| `401` `{"message": "Access is denied"}` (con token válido)        | La orden no existe o no pertenece a tu tienda.                                                             |

### Eventos que no dependen de ti

Con **despacho por Intercorp Retail**, también recibirás `ORDER_DELIVERY`, `ORDER_PENDING_WITHDRAWAL` y `ORDER_RETIRED` como informativos.

| Webhook              | Significado                      | Qué hacer                                             |
| -------------------- | -------------------------------- | ----------------------------------------------------- |
| `ORDER_CANCEL`       | Orden cancelada                  | **No atender.** Si ya la preparaste, no la despaches. |
| `ORDER_IN_ANNULMENT` | Solicitud de anulación en curso  | Esperar resolución antes de despachar.                |
| `ORDER_IN_RETURN`    | Solicitud de devolución en curso | Preparar recepción de la devolución.                  |
| `ORDER_RETURNED`     | Orden devuelta                   | Reingresar el stock si corresponde.                   |

### Integración recomendada

1. Recibe las órdenes nuevas por el webhook `ORDER_READY_FOR_HANDLING` y guarda los datos de despacho que trae. Como respaldo, consulta **Listar órdenes** con `status=ready-for-handling` cada 5–10 minutos.
2. Obtén el **Detalle de orden**, revisa el tipo de entrega e **inicia el manejo** lo antes posible.
3. Al despachar, **factura** y **sube el comprobante**.
4. Con **despacho propio**, **confirma la entrega** cuando el cliente reciba el pedido.