Crear pedido

Crea un pedido OPEN para el cliente autenticado, o devuelve el carrito abierto que ya existe para el mismo alcance. Los canales propios suelen hacer POST de un pedido vacío con el alcance y luego actualizarlo a medida que cambia el carrito.

Requiere un access token de la API Storefront obtenido mediante intercambio de token.

Cuerpo de la solicitud

Campo	Requerido	Tipo	Descripción
`id`	Sí	string	Id externo del pedido que asignas. Único por comercio. 1–64 caracteres.
`store_id`	Sí	string	Identificador externo de la tienda
`channel_id`	Sí	string	Identificador externo del canal
`fulfillment_id`	Sí	string	Opción de fulfillment externa
`brand_id`	No	string	Identificador externo de marca cuando aplica
`is_anonymous`	No	boolean	Checkout invitado. Por defecto `false`.
`customer`	Sí	object	Snapshot del cliente en el pedido (`customer_info`, address/billing opcionales). Lo arma el canal/SDK — Fire spark no carga la fila del customer.
`lines`	No	array	Líneas de pedido con precios (`OrderLine`). Por defecto `[]`.
`totals`	No	object	Totales del pedido. Por defecto en cero.
`metadata`	No	object	Metadatos del canal. Por defecto `{}`.
`redeem`	No	array	Canjes del pedido. Cada uno necesita `payment_id` (un pago `REDEMPTION` activo) y `amount`; `before_taxes` es `true` por defecto. Por defecto `[]`.
`redemption_steps`	No	array	Canjes aplicados en orden. El servidor los recalcula y guarda a partir de `lines`, `totals` y `redeem`. Por defecto `[]`.

Los pagos no forman parte del create. Guárdalos después con Guardar intent de pago. payment_status arranca en IDLE.

Solicitud

curl -X POST "https://firespark.cloud/api/storefront/v1/orders" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "ord-48291",
    "brand_id": "0001",
    "store_id": "downtown",
    "channel_id": "app",
    "fulfillment_id": "delivery",
    "is_anonymous": false,
    "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
    },
    "metadata": {
      "cart_session_id": "sess_abc123"
    }
  }'

Respuesta

El cuerpo siempre es { data: Order }. El status indica si se creó o se reutilizó:

Estado	Significado
`201`	Se creó un pedido `OPEN` nuevo
`202`	Ya existe un `OPEN` para este cliente + tienda + canal + fulfillment + marca. `data` es ese carrito — usa su `id`

Un cliente solo puede tener un carrito OPEN por alcance. POSTs concurrentes no crean un segundo carrito.

Genera el id externo en tu servidor antes del POST para reintentar si falla la red. Un reintento con un id nuevo igual devuelve 202 y el carrito existente si el alcance ya tiene un OPEN. Un id duplicado en otro pedido (que no esté abierto) sigue siendo 422. @fire-spark/core Order.create arma el snapshot customer desde name/email/phone.

Errores

Estado	Descripción
`401`	Token ausente o inválido
`422`	Cuerpo inválido o id de pedido duplicado

Documentación de API

Endpoints

Guías

Recursos

Cuerpo de la solicitud

Solicitud

Respuesta

Errores

​Cuerpo de la solicitud

​Solicitud

​Respuesta

​Errores

Cuerpo de la solicitud

Solicitud

Respuesta

Errores