API atual/Referência completa/Pedidos e conta do cliente

POSTCriar pedido

Transforma o carrinho do cliente logado em pedido, com frete, cupom, pagamento e endereços.

Transforma o carrinho do cliente logado em um pedido. É a última chamada do checkout: o cliente já escolheu o endereço, a forma de entrega e a forma de pagamento, e esta rota grava a compra, reserva o estoque, aplica cupom e desconto, esvazia o carrinho e devolve o pedido já com o status inicial.

O servidor não confia nos valores que o cliente manda. Os itens vêm do carrinho do servidor, os preços vêm do catálogo, e frete, desconto, imposto e total são recalculados. Se o que você enviou diverge do que o servidor calculou, ele recusa (veja "Erros") em vez de aceitar o número do cliente. Quem compra sem conta usa a rota de pedido de visitante.

POST/api/v1/storefront/ordersCliente

Cria um pedido a partir do carrinho do cliente

Cabeçalhos

Authorizationstringobrigatório

Bearer <token do cliente>.

X-Session-IDstring

Opcional. Id da sessão de um carrinho de visitante que ainda não foi mesclado ao do cliente. Normalmente você já fez o merge do carrinho no login e não precisa dele.

Corpo da requisição

payment_methodstringobrigatório

Código da forma de pagamento escolhida (pix, credit_card...), uma das que a loja lista para o cliente. Código inexistente ou inativo é recusado com payment_not_found / payment_inactive.

billing_address_iduuid

Id de um endereço do caderno de endereços do cliente, usado como cobrança. O servidor copia o endereço para dentro do pedido e só usa ids de endereços do próprio cliente.

shipping_address_iduuid

Id do endereço de entrega, do mesmo caderno.

billing_addressobject

Alternativa a billing_address_id: o endereço completo na hora. Campos: first_name, last_name, address_line1, address_line2, district, complement, city, state (UF), postal_code (CEP), country (BR), phone, cpf (CPF ou CNPJ do comprador). Quando só o id vem, o servidor preenche o resto.

shipping_addressobject

Alternativa a shipping_address_id, com os mesmos campos.

shipping_selectionsarray

Forma de entrega escolhida por seller: itens { "vendor_id": uuid, "shipping_method_id": uuid, "service_code": string }. Use os ids que a cotação de frete devolveu. Sem escolha válida o servidor responde 409 shipping_requote_required.

shipping_totalinteger

Frete somado, em centavos, como a cotação mostrou ao cliente. O servidor recalcula; se não bater, responde shipping_requote_required.

itemsarray

Opcional. Se omitido, os itens vêm do carrinho do servidor (o caminho recomendado). Se enviado, cada linha (product_id, variation_id, quantity, options, note) precisa ser idêntica ao carrinho, senão 409 cart_mismatch.

coupon_codestring

Cupom aplicado no carrinho. O servidor revalida o cupom e calcula o desconto; o discount_total do cliente nunca é aceito.

customer_notesstring

Observação do cliente para a loja.

installmentsinteger

Número de parcelas desejado no cartão. É só uma dica: os juros são sempre recalculados pelo servidor com a configuração da loja.

idempotency_keystring

Chave única da tentativa. Reenviar a mesma chave devolve o pedido já criado (200) em vez de criar outro. Gere uma por clique em "Finalizar" e reaproveite em caso de repetição.

terms_acceptedboolean

true quando o cliente marcou o aceite dos termos. Só é exigido se a loja ligou o aceite obrigatório (senão 422 terms_not_accepted).

pickup_warehouse_iduuid

Retirada na loja: id do ponto de retirada escolhido. O pedido gera um código de 6 dígitos de retirada.

buy_nowboolean

Compra expressa de um item só, sem passar pelo carrinho (items é então obrigatório).

redeem_pointsinteger

Pontos de fidelidade a resgatar como desconto.

wallet_amountinteger

Saldo da carteira da loja a usar, em centavos.

voucher_codestring

Código de vale a resgatar.

gift_cert_codestring

Código de vale-presente a debitar.

invoiced_plan_iduuid

Plano de parcelas, só quando a forma de pagamento é "faturado" (B2B).

accept_credit_splitboolean

B2B: aceita dividir o pedido entre faturado e PIX quando o limite de crédito não cobre tudo.

Campos de identidade como customer_id, customer_email e customer_name são ignorados: o comprador é sempre o dono do token. Outros campos do corpo existem para usos específicos (share_ref_code, source_channel, metadata) e não são necessários numa loja comum.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/orders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "payment_method": "pix",
  "billing_address_id": "04d6da67-1f55-427c-885d-0a30bdbf264d",
  "shipping_address_id": "04d6da67-1f55-427c-885d-0a30bdbf264d",
  "shipping_total": 1000,
  "shipping_selections": [
    {
      "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
      "shipping_method_id": "50000000-0000-0000-0000-000000000001"
    }
  ],
  "customer_notes": "Deixar na portaria.",
  "idempotency_key": "checkout-2026-10-11-0001"
}'

Resposta

201Pedido criado

json

{
  "order": {
    "id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
    "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
    "order_number": "PEDIDO-20261011-0009",
    "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
    "company_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
    "company_name": "Loja Exemplo",
    "customer_id": "264a70c1-9c69-458d-ac73-838543f87da2",
    "customer_name": "Maria Souza",
    "customer_email": "maria.souza@example.com",
    "subtotal": 4990,
    "shipping_total": 1000,
    "tax_total": 0,
    "discount_total": 724,
    "total": 5266,
    "currency": "BRL",
    "payment_method": "pix",
    "payment_method_name": "PIX",
    "payment_status": "pending",
    "sales_channel": "web",
    "shipping_method_id": "50000000-0000-0000-0000-000000000001",
    "shipping_method_name": "Entrega Padrão",
    "min_delivery_days": 10,
    "max_delivery_days": 10,
    "is_guest": false,
    "status": "O",
    "status_text": "pending",
    "total_str": "52.66",
    "subtotal_str": "49.90",
    "shipping_cost_str": "10.00",
    "discount_str": "7.24",
    "timestamp": 1791752125,
    "created_at": "2026-10-11T20:55:25.558277Z",
    "updated_at": "2026-10-11T20:55:25.558277Z"
  },
  "items": [
    {
      "id": "a43b9f10-5590-424b-87c8-dffa34bae43d",
      "product_id": "a34f126e-ff3b-4779-bf74-bda03502136e",
      "product_name": "Caneca Exemplo",
      "product_sku": "CAN-002",
      "unit_price": 4990,
      "quantity": 1,
      "discount": 724,
      "tax": 0,
      "total": 4266,
      "options": {}
    }
  ],
  "addresses": [
    {
      "address_type": "billing",
      "first_name": "Maria",
      "last_name": "Souza",
      "address_line1": "Avenida Paulista, 1000",
      "address_line2": "Apto 52",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310-100",
      "country": "BR",
      "phone": "11987654321",
      "cpf": "123.456.789-09"
    },
    {
      "address_type": "shipping",
      "first_name": "Maria",
      "last_name": "Souza",
      "address_line1": "Avenida Paulista, 1000",
      "address_line2": "Apto 52",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310-100",
      "country": "BR",
      "phone": "11987654321",
      "cpf": "123.456.789-09"
    }
  ],
  "status_history": [
    {
      "old_status": "pending",
      "new_status": "pending",
      "reason": "order_created",
      "created_at": "2026-10-11T20:55:25.558277Z"
    }
  ]
}

O corpo tem o mesmo formato de Consultar pedido (order, items, addresses, status_history), sem os campos de retomada. O status inicial costuma ser pending (letra O) e payment_status começa pending. Se a chave de idempotency_key já tinha gerado um pedido, a resposta é 200 com o pedido existente. Na divisão entre faturado e PIX a resposta é 201 e o pedido principal já abre a janela de retomada do pagamento.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON, carrinho vazio, ou recusa de pontos, carteira, vale ou vale-presente	`{"error":"cart is empty"}`
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
409	`items` diverge do carrinho	`{"error":"cart_mismatch","detail":"client items differ from server cart"}`
409	Frete desatualizado, endereço mudou ou entrega não escolhida	`{"error":"shipping_requote_required","message":"O frete precisa ser recalculado. ..."}`
409	Pedido igual feito há pouco, carrinho já virou pedido ou pedido em processamento	`{"error":"duplicate_order"}` / `{"error":"cart_already_ordered"}` / `{"error":"order_in_progress","retry_after_ms":1500}`
412	B2B: pedido faturado acima do limite de crédito	`{"error":"credit_limit_exceeded",...}`
422	Validação antes de criar: estoque, preço, forma de pagamento, entrega ou pedido mínimo. Todas as falhas vêm juntas.	`{"error":"order validation failed","validation_errors":[{"field":"items","code":"insufficient_stock","message":"..."}]}`
422	Termos não aceitos, e-mail não verificado, política de endereço da loja, destino não atendido, limite de gastos da conta, forma de pagamento bloqueada para o cliente	`{"error":"terms_not_accepted"}` / `{"error":"email_not_verified"}` / `payment_method_not_allowed` / `spending_limit_exceeded` / `destination_not_allowed`
500	Falha ao finalizar o pedido	`{"error":"Não foi possível finalizar o pedido. Tente novamente ou entre em contato com o suporte."}`

Veja também