API atual/Referência completa/Sessão do cliente

Pedido de visitante

Cria um pedido para quem compra sem conta, a partir do carrinho da sessão.

É o passo final do checkout de quem não tem conta: o visitante já montou o carrinho com o mesmo X-Session-ID, informou contato e endereços, e esta rota transforma o carrinho em pedido. Se o cliente estiver logado (token no cabeçalho), a mesma rota cria o pedido em nome dele e ignora os campos guest_*.

O servidor não confia nos valores do cliente: refaz os itens a partir do carrinho da sessão, recalcula frete, descontos (cupom, PIX) e impostos, e só então grava. Valores monetários são inteiros em centavos (2190 = R$ 21,90).

POST/api/v1/storefront/guest/ordersPública

Criar pedido de visitante

Cabeçalhos

X-Session-IDstringobrigatório

Sessão do carrinho do visitante.

Corpo da requisição

guest_emailstringobrigatório

E-mail do visitante. Precisa conter @ e ..

guest_namestringobrigatório

Nome completo do visitante.

guest_phonestring

Telefone de contato.

payment_methodstringobrigatório

Código da forma de pagamento da loja (pix, credit_card, boleto...).

shipping_addressobjectobrigatório

Endereço de entrega.

first_namestringobrigatório

Nome.

last_namestring

Sobrenome.

address_line1stringobrigatório

Logradouro e número.

address_line2string

Complemento.

districtstring

Bairro.

citystringobrigatório

Cidade.

statestringobrigatório

UF.

postal_codestringobrigatório

CEP.

countrystringobrigatório

País (BR).

phonestring

Telefone.

cpfstring

CPF do destinatário, quando a loja pede.

billing_addressobjectobrigatório

Endereço de cobrança, com os mesmos campos de shipping_address.

itemsarray

Linhas do pedido (product_id uuid, variation_id, quantity). Opcional: o padrão é o carrinho da sessão.

shipping_method_iduuid

Forma de envio escolhida. O frete é recalculado no servidor.

coupon_codestring

Cupom aplicado. O desconto é revalidado no servidor.

customer_notesstring

Observação do cliente.

idempotency_keystring

Chave de repetição segura, escolhida por você.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/guest/orders" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "guest_email": "maria.souza@example.com",
  "guest_name": "Maria Souza",
  "guest_phone": "(11) 91234-5678",
  "payment_method": "pix",
  "shipping_address": {
    "first_name": "Maria",
    "last_name": "Souza",
    "address_line1": "Av. Paulista, 1000",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01310-100",
    "country": "BR",
    "cpf": "123.456.789-09"
  },
  "billing_address": {
    "first_name": "Maria",
    "last_name": "Souza",
    "address_line1": "Av. Paulista, 1000",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01310-100",
    "country": "BR"
  },
  "idempotency_key": "ck-2026-10-11-0001"
}'

Resposta

201Pedido criado

json

{
  "id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
  "order_number": "PEDIDO-20261011-0007",
  "customer_id": "",
  "status": "pending",
  "subtotal": 29900,
  "shipping_total": 2190,
  "tax_total": 0,
  "discount_total": 1495,
  "total": 30595,
  "currency": "BRL",
  "payment_method": "pix"
}

A resposta é o objeto do pedido, o mesmo de Consultar pedido (o exemplo acima está resumido). Todos os valores estão em centavos. customer_id vem vazio em pedido de visitante. Uma repetição com a mesma idempotency_key responde 200 com o pedido já criado.

Erros

Status	Quando	Exemplo de corpo
400	Falta `guest_email` ou `guest_name`, e-mail mal formado, carrinho vazio, ou resgate de pontos/carteira por visitante.	`{"error":"guest_email is required for guest checkout"}`
403	Compra de visitante desligada na loja.	`{"error":"guest checkout is not enabled"}`
409	`items` enviados diferem do carrinho do servidor.	`{"error":"cart_mismatch","detail":"client items differ from server cart"}`
422	E-mail ainda não verificado por código.	`{"error":"email_not_verified","message":"Please verify your email before placing an order"}`
422	Falha de validação do pedido (estoque, endereço, regras da loja).	`{"error":"order validation failed","validation_errors":[...]}`
429	Limite de requisições da família `/storefront/`.	`{"error":"rate limit exceeded","detail":"too many requests, please try again later"}`

Veja também