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

# Ciclo de vida del pedido

> Cada estado por el que pasa un pedido, cómo lo impulsan sus decisiones y los campos de preparación y pago que incluye.

Un pedido pasa por un conjunto definido de estados. Maple lo crea y gestiona el pago y las transiciones que ve el cliente; usted impulsa la preparación aceptándolo e informando su avance. Esta página es la referencia de cada estado, las transiciones entre ellos y los campos relacionados del recurso del pedido. Para construir el ciclo, consulte [Reciba y decida pedidos](https://docs.maple.inc/es/developer-api/guides/receive-orders.md).

## Estados

El `status` del recurso del pedido siempre es uno de estos nueve valores:

| Estado               | Significado                                      | Lo establece                            |
| -------------------- | ------------------------------------------------ | --------------------------------------- |
| `PENDING`            | Creado y a la espera de una decisión             | Maple (estado inicial)                  |
| `ACCEPTED`           | Usted aceptó el pedido                           | su `accept` / `status: ACCEPTED`        |
| `AUTO_ACCEPTED`      | Aceptado automáticamente al enviarse             | Maple — trátelo como `ACCEPTED`         |
| `READY`              | Listo para recoger o para entregar al repartidor | su `ready` / `status: READY`            |
| `IN_DELIVERY`        | En camino                                        | su `status: IN_DELIVERY`                |
| `FULFILLED`          | Completado                                       | su `complete` / `status: FULFILLED`     |
| `REJECTED`           | Rechazado, o no se pudo enviar a usted           | su `deny` / `status: REJECTED`          |
| `STORE_CANCELLED`    | Cancelado por el local después de aceptarse      | su `cancel` / `status: STORE_CANCELLED` |
| `CUSTOMER_CANCELLED` | El cliente lo canceló                            | Maple                                   |

`FULFILLED`, `REJECTED`, `STORE_CANCELLED` y `CUSTOMER_CANCELLED` son **terminales**: un pedido en uno de estos estados ya no cambiará.

> [!NOTE]
>
> Usted establece el estado mediante los [endpoints de decisión](https://docs.maple.inc/es/developer-api/guides/receive-orders.md). `PENDING`, `AUTO_ACCEPTED` y `CUSTOMER_CANCELLED` son estados del sistema que usted observará pero nunca establecerá.

## Cómo fluye

```
stateDiagram-v2
  [*] --> PENDING
  PENDING --> ACCEPTED: accept
  PENDING --> REJECTED: deny
  ACCEPTED --> READY: ready
  READY --> IN_DELIVERY: status (delivery)
  READY --> FULFILLED: complete
  IN_DELIVERY --> FULFILLED: complete
  ACCEPTED --> STORE_CANCELLED: cancel
  READY --> STORE_CANCELLED: cancel
  FULFILLED --> [*]
  REJECTED --> [*]
  STORE_CANCELLED --> [*]
```

El camino ideal es `PENDING → ACCEPTED → READY → FULFILLED`, con `IN_DELIVERY` entre `READY` y `FULFILLED` en los pedidos a domicilio. Desde `PENDING` usted acepta o rechaza. Después de aceptar, todavía puede cancelar (`STORE_CANCELLED`) hasta que el pedido se complete. Que el cliente cancele (`CUSTOMER_CANCELLED`) puede interrumpir cualquier estado no terminal y llega como un webhook `order.cancelled`.

Las transiciones se validan: una decisión que no es válida desde el estado actual se rechaza. Como toda decisión es [segura ante repeticiones](https://docs.maple.inc/es/developer-api/concepts/idempotency.md), repetirla es inofensivo.

## Cómo se traducen sus decisiones en estados

| Llamada                      | Estado resultante                                                                                   |
| ---------------------------- | --------------------------------------------------------------------------------------------------- |
| `POST /orders/{id}/accept`   | `ACCEPTED`                                                                                          |
| `POST /orders/{id}/deny`     | `REJECTED`                                                                                          |
| `POST /orders/{id}/ready`    | `READY`                                                                                             |
| `POST /orders/{id}/complete` | `FULFILLED`                                                                                         |
| `POST /orders/{id}/cancel`   | `STORE_CANCELLED`                                                                                   |
| `POST /orders/{id}/status`   | el valor que envíe (`ACCEPTED`, `READY`, `IN_DELIVERY`, `FULFILLED`, `REJECTED`, `STORE_CANCELLED`) |

## Cuándo se envía cada webhook

Aquí se ve dónde cae cada webhook a lo largo de la vida de un pedido. Las flechas punteadas son webhooks que Maple le envía; las flechas sólidas son llamadas que usted hace de vuelta.

```
sequenceDiagram
  participant C as Customer
  participant M as Maple
  participant You as Your app
  C->>M: Places an order
  M-->>You: order.created
  opt You subscribed to validation
    M-->>You: order.validation_requested
    You->>M: validation_result (valid / invalid)
  end
  M-->>You: order.notification
  You->>M: accept
  M-->>You: order.paid
  You->>M: ready, then complete
  opt Customer or store cancels
    M-->>You: order.cancelled
  end
```

1. **`order.created`**: el pedido ya existe. Se envía use o no la validación.
2. **`order.validation_requested`** *(solo si se suscribió)*: Maple le pide confirmar que el pedido se puede preparar y espera su `validation_result`. Un resultado `invalid` rechaza el pedido aquí, así que nunca llega a la notificación.
3. **`order.notification`**: el pedido se le entrega para prepararlo. Usted hace `accept` (o `deny`) y luego informa `ready` y `complete`.
4. **`order.paid`**: el pago se liquidó. Su posición varía: un pedido con pago mediante enlace puede pagarse antes de la notificación, mientras que un pedido con pago en el local se paga después; no suponga que llega en un punto fijo.
5. **`order.cancelled`**: el cliente o el local canceló. Puede llegar casi en cualquier momento después de la creación, incluso después de que usted empezó a prepararlo. Deténgase cuando llegue.

Ninguna de sus propias transiciones (`accept`, `ready`, `complete`) regresa como webhook, y no hay un evento para cada cambio de estado; vea abajo.

## Los webhooks no siguen cada transición

No hay un webhook para cada cambio de estado. Maple emite un conjunto fijo de eventos de pedido: `order.notification`, `order.created`, `order.paid`, `order.cancelled` y, si se suscribe, `order.validation_requested`. Las transiciones que **usted** impulsa (`accept`, `ready`, `complete`) no se le devuelven, y no hay un evento para llegar a `IN_DELIVERY` ni para que el pago pase a `refunded`, `voided` o `failed`.

Por eso, **el recurso del pedido es la fuente de verdad del estado actual, no el flujo de eventos.** Cuando necesite saber en qué punto está un pedido, lea `GET /v1/orders/{orderId}`. Los webhooks le avisan que algo ocurrió; el recurso le dice el estado. Consulte [Webhooks](https://docs.maple.inc/es/developer-api/concepts/webhooks.md).

## Tipo de entrega

Cada pedido incluye un `fulfillment_type`, uno de:

| Valor      | Significado                                                 |
| ---------- | ----------------------------------------------------------- |
| `pickup`   | El cliente recoge el pedido                                 |
| `delivery` | El pedido se entrega a domicilio; aquí aplica `IN_DELIVERY` |

Los pedidos a domicilio también incluyen `delivery_address`: calle, unidad, ciudad, estado, código postal y las instrucciones de entrega del cliente en `notes`. Es `null` en pedidos para recoger y en pedidos a domicilio sin dirección guardada. Consulte [Recibir pedidos](https://docs.maple.inc/es/developer-api/guides/receive-orders.md).

## El pago es de solo lectura

Maple es dueño de todo el ciclo de pago del cliente, de principio a fin. El pago **nunca es algo que usted cree o cambie**: no existe un endpoint de pagos. Solo lo lee, como campos del pedido:

```json
"payment_status": "paid",
"payment": { "provider": "stripe", "status": "paid", "payment_link_url": "https://..." }
```

`payment_status` y `payment.status` son el mismo valor, uno de:

| Estado del pago      | Significado              |
| -------------------- | ------------------------ |
| `pending`            | A la espera de pago      |
| `paid`               | Pagado                   |
| `failed`             | El intento de pago falló |
| `voided`             | Autorización anulada     |
| `refunded`           | Reembolsado por completo |
| `partially_refunded` | Reembolsado parcialmente |

`payment_link_url` es el enlace alojado por Maple mediante el cual el cliente paga. Es `null` en pedidos con pago en el local y antes de que se haya creado un enlace. Trate todo esto como autorizado y de solo lectura; consulte [Cómo funciona Maple](https://docs.maple.inc/es/developer-api/how-maple-works.md).