Realizar pedidos

​

El recorrido en términos simples

1. Explorar — El cliente elige tienda, canal y fulfillment_id, y carga el menú compuesto.
2. Personalizar — Usa @fire-spark/storefront (createSession / toOrderLines) para convertir un producto personalizado en filas OrderLine con precios.
3. Abrir carrito — Llama a Crear pedido con el alcance (y normalmente lines vacías). 201 es un carrito nuevo; 202 es el OPEN que ya existe para ese alcance — usa el id de la respuesta.
4. Sincronizar carrito — Aplica debounce a los cambios locales y Actualizar pedido con lines + totals.
5. Validar — Antes del checkout, llama a Validar pedido (o order.validateOrder() en @fire-spark/storefront) para comprobar precios y disponibilidad contra un menú fresco.
6. Pagar y colocar — Guarda los tenders con Guardar intent de pago (order.setTenders) o pasa un solo método al colocar. Luego llama a Colocar pedido (order.placeOrder()). Pasa intent_id para bloquear ese borrador. Omítelo para armar un tender real desde payment.type más un tender REDEMPTION por cada payment_id de canje. No hay efectivo por defecto: sin intent_id ni payment.type, place falla con PAYMENT_REQUIRED salvo que los canjes cubran el total (entonces solo tenders REDEMPTION). El carrito pasa a CLOSED y arranca fulfillment.
7. Seguimiento — Suscríbete con realtime.listenOrder({ orderId }) (ver Emitir token realtime) o consulta Obtener fulfillment para checkout_state, estados visitados y current_node_ids. En el historial usa Listar fulfillments en vez de un GET por pedido. Obtener pedido sigue exponiendo fulfillment_status. Cómo espera el overlay se configura en el workflow de fulfillment.

​

Requisitos previos

• Cliente registrado y autenticado mediante intercambio de token
• Ids de tienda, canal y fulfillment desde Listar tiendas y Listar fulfillment
• Menú cargado para la misma combinación de tienda, canal y fulfillment

​

Paso 1 — Generar líneas con precio desde la personalización

import { createSession, indexMenu, toOrderLines } from "@fire-spark/storefront";

const lookup = indexMenu(menu);
const session = createSession(lookup, productId);
// ... el cliente elige modificadores vía session ...
const lines = toOrderLines(session.root);

​

Paso 2 — Asignar ids antes de crear

const orderId = `ord-${crypto.randomUUID().slice(0, 8)}`;

​

Paso 3 — Crear y luego actualizar el pedido

curl -X POST "https://firespark.cloud/api/storefront/v1/orders" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "ord-48291",
    "store_id": "downtown",
    "channel_id": "app",
    "fulfillment_id": "delivery",
    "customer": {
      "customer_info": {
        "display_name": "Ada Lovelace",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com",
        "phone": "+15551234567"
      }
    },
    "lines": [],
    "totals": {
      "currency": "USD",
      "subtotal": 0,
      "discount_rate": 0,
      "discount_total": 0,
      "tax_rate": 0,
      "tax_total": 0,
      "total": 0
    }
  }'

​

Paso 4 — Validar antes del checkout

curl -X POST "https://firespark.cloud/api/storefront/v1/orders/validate" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "downtown",
    "channel_id": "app",
    "fulfillment_id": "delivery",
    "lines": [],
    "totals": {
      "currency": "USD",
      "subtotal": 0,
      "discount_rate": 0,
      "discount_total": 0,
      "tax_rate": 0,
      "tax_total": 0,
      "total": 0
    }
  }'

​

Paso 5 — Colocar el pedido

await order.setTenders([
  {
    method: "CARD",
    provider: "kushki",
    collect_at: "DEVICE",
    allocation: null
  }
]);
await order.placeOrder();

​

Paso 6 — Mostrar el estado al cliente

​

Paso 7 — Cancelar o reembolsar

​

Enlaces relacionados