Ir al contenido
Maple

    Pedidos

    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.

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

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

    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.

    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:

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