> ## 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](/es/developer-api/guides/receive-orders).

## 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](/es/developer-api/guides/receive-orders).
  `PENDING`, `AUTO_ACCEPTED` y `CUSTOMER_CANCELLED` son estados del sistema que usted observará pero nunca establecerá.
</Note>

## Cómo fluye

```mermaid theme={null}
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](/es/developer-api/concepts/idempotency), 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.

```mermaid theme={null}
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](/es/developer-api/concepts/webhooks).

## 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](/es/developer-api/guides/receive-orders).

## 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 theme={null}
"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](/es/developer-api/how-maple-works).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.