VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Checkout

Iniciar e ler o checkout

Abre uma sessão de checkout a partir de um carrinho e lê a sessão com os fretes e pagamentos que a loja oferece.

POST /checkout cria a sessão de checkout a partir de um carrinho que já tem itens. A sessão congela o ponto de partida (subtotal e descontos de catálogo) e passa a ser a fonte dos valores até o pedido ser criado. GET /checkout/{sessionId} devolve a sessão junto com os itens, os fretes disponíveis e os pagamentos disponíveis para esse carrinho e esse endereço.

Abrir a sessão não reserva estoque nem cobra nada. Se o carrinho tinha um cupom gravado (Cupons no carrinho), a API tenta aplicá-lo à sessão; se ele não vale mais, a sessão abre sem o cupom e sem erro.

Iniciar o checkout

POST/api/v1/storefront/checkoutAutenticada

Inicia uma sessão de checkout a partir de um carrinho

Cliente logado pode omitir cart_id: a API usa o carrinho ativo dele. Visitante precisa mandar cart_id e guest_email. Antes de criar a sessão, a API confere se o carrinho é de quem chama (mesmo usuário ou mesmo X-Session-ID).

Cabeçalhos

Authorizationstring
Bearer <token> do cliente logado.
X-Session-IDstring
Identificador do visitante, o mesmo usado no carrinho. Obrigatório sem token.
Content-Typestringobrigatório
application/json.

Corpo da requisição

cart_iduuid
Id do carrinho (campo id de GET /cart). Obrigatório para visitante. Cliente logado pode omitir.
guest_emailstring
E-mail do comprador. Obrigatório quando não há login.
guest_namestring
Nome do visitante. Opcional.
guest_phonestring
Telefone do visitante. Opcional.

Exemplo de requisição

Resposta

201Sessão criada

Campos da resposta

iduuid
Id da sessão. É o {sessionId} de todas as outras rotas.
tenant_iduuid
Loja dona da sessão. Informativo.
cart_iduuid
Carrinho de origem.
user_idstring
Id do cliente logado. Vazio para visitante.
is_guestboolean
true quando não há login.
guest_emailstring
E-mail informado na abertura. Ausente em sessão de cliente logado.
stepstring
addressshippingpaymentreview
Etapa atual. Veja a home da seção.
shipping_addressobject|null
Endereço de entrega. null até gravar o endereço.
billing_addressobject|null
Endereço de cobrança. Igual ao de entrega quando você não manda outro.
shipping_method_iduuid|null
Frete escolhido.
shipping_costinteger
Frete em centavos. 0 até escolher o frete ou quando ele é grátis.
payment_methodstring|null
Código do pagamento escolhido (pix, credit_card...).
subtotalinteger
Soma dos itens em centavos, antes de descontos.
discountinteger
Desconto total em centavos: catálogo + contrato B2B + regional + cupom.
catalog_discountinteger
Parte do desconto vinda de promoções automáticas de catálogo.
b2b_discountinteger
Parte vinda de tabela de preço B2B do comprador.
state_discountinteger
Ajuste de preço por estado. Pode ser negativo.
pix_discountinteger
Desconto do pagamento por PIX, em centavos. 0 até o PIX ser escolhido.
taxinteger
Impostos em centavos.
tax_includedboolean
true quando os preços da loja já incluem imposto: o valor é registrado, mas não somado ao total.
totalinteger
Total a cobrar, em centavos.
coupon_codestring|null
Cupom aplicado.
free_shippingboolean
true quando o cupom concede frete grátis.
gift_cert_amountinteger
Valor abatido por vale-presente, em centavos.
cpfstring
CPF ou CNPJ gravado na etapa de endereço.
document_typestring
cpfcnpj
Tipo do documento, deduzido do número.
created_atstring
RFC 3339, UTC. A sessão expira 2 horas depois.

A resposta traz outros campos opcionais que só aparecem quando se aplicam (line_ids, tax_breakdown, promised_delivery_date, installments, e afins). Eles são omitidos quando vazios.

Erros

StatusQuandoCorpo
400Visitante sem guest_email{"error":"guest_email is required for guest checkout"}
400Sem cart_id e sem login{"error":"cart_id is required"}
400Cliente logado sem carrinho ativo{"error":"no active cart found for user"}
400Carrinho sem itens{"error":"cart is empty"}
400Corpo que não é JSON{"error":"invalid request body"}
403Loja com checkout de visitante desligado{"error":"guest checkout is not enabled"}
404cart_id inexistente ou que não é do chamador (outro usuário ou outro X-Session-ID){"error":"cart not found"}
Checkout de visitante e o 404

Se o cart_id pertence a outro visitante ou a outro cliente, a API responde 404 cart not found e não revela que o carrinho existe. Antes de concluir que o carrinho "sumiu", confira se você mandou o mesmo X-Session-ID (ou o mesmo token) que criou o carrinho.

Ler a sessão e as opções

GET/api/v1/storefront/checkout/{sessionId}Autenticada

Consulta a sessão de checkout com as opções de envio e pagamento disponíveis

Chame depois de gravar o endereço para obter os fretes que atendem aquele CEP. A lista de pagamentos já considera o seller dos itens, o grupo do cliente e o valor do pedido. A resposta não é guardada em cache.

Parâmetros de caminho

sessionIduuidobrigatório
Id devolvido por POST /checkout.

Cabeçalhos

Authorizationstring
Bearer <token> do dono da sessão.
X-Session-IDstring
Mesmo identificador do visitante que abriu a sessão.

Exemplo de requisição

Resposta

200Sessão com opções

Campos da resposta

sessionobject
A sessão completa, no mesmo formato de POST /checkout (aqui encurtada).
itemsarray
Linhas do carrinho cobertas pela sessão (mesmo formato de Ler o carrinho).
available_shippingarray
Fretes que atendem este carrinho e endereço.
available_shipping[].iduuid
Valor para shipping_method_id em Escolher o frete.
available_shipping[].namestring
Nome para exibir.
available_shipping[].codestring
Código interno do método.
available_shipping[].costinteger
Custo em centavos.
available_shipping[].estimated_daysinteger
Prazo estimado em dias. 0 quando a loja não informa.
available_shipping[].free_shippingboolean
true quando o frete é grátis para este pedido.
available_shipping[].service_codestring
Presente quando um método agregador se desdobra em vários serviços (PAC, SEDEX...). Envie-o junto em service_code.
available_paymentarray
Formas de pagamento permitidas.
available_payment[].iduuid
Id interno da forma de pagamento.
available_payment[].namestring
Nome para exibir.
available_payment[].codestring
Valor para payment_method em Escolher o pagamento.
change_linesarray
Tarifas e descontos extras que uma regra personalizada da loja acrescentou à prévia. Ausente na maioria das lojas.

Erros

StatusQuandoCorpo
404Sessão inexistente, expirada, de outra loja ou de outro dono{"error":"checkout session not found"}
Sessão que não é sua parece inexistente

Por segurança a API usa o mesmo 404 para sessão que não existe e para sessão de outra pessoa. Se o seu GET falha logo após o POST, o suspeito principal é o X-Session-ID diferente entre as duas chamadas.

Veja também

  • Endereço, frete e pagamento
  • Carrinho: ler e esvaziar
  • Calcular o carrinho
Anterior
Checkout
Próxima
Endereço, frete e pagamento
Nesta página
  • Iniciar o checkout
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ler a sessão e as opções
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl -X POST "$BASE_URL/api/v1/storefront/checkout" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "cart_id": "caad0bcd-177e-47cc-a02a-0ad63a47ee21",
  "guest_email": "maria.souza@example.com",
  "guest_name": "Maria Souza",
  "guest_phone": "11987654321"
}'
bash
curl "$BASE_URL/api/v1/storefront/checkout/$CHECKOUT_ID" \
  -H "X-Session-ID: $SESSION_ID"
json
{
  "id": "f9f26cde-bc64-4d49-ab14-e3fe35971432",
  "tenant_id": "dfe2555e-bfd0-41a8-9fa1-9586999f3798",
  "cart_id": "caad0bcd-177e-47cc-a02a-0ad63a47ee21",
  "user_id": "",
  "is_guest": true,
  "guest_email": "maria.souza@example.com",
  "guest_name": "Maria Souza",
  "guest_phone": "11987654321",
  "step": "address",
  "shipping_address": null,
  "billing_address": null,
  "shipping_method_id": null,
  "shipping_cost": 0,
  "payment_method": null,
  "subtotal": 30000,
  "discount": 7500,
  "catalog_discount": 7500,
  "b2b_discount": 0,
  "state_discount": 0,
  "pix_discount": 0,
  "tax": 0,
  "tax_included": false,
  "total": 22500,
  "coupon_code": null,
  "free_shipping": false,
  "gift_cert_amount": 0,
  "cpf": "",
  "document_type": "",
  "notes": "",
  "created_at": "2026-10-11T23:47:52.521200805Z",
  "updated_at": "2026-10-11T23:47:52.521200805Z"
}
json
{
  "session": { "id": "f9f26cde-bc64-4d49-ab14-e3fe35971432", "step": "shipping", "subtotal": 30000, "total": 22500 },
  "items": [
    {
      "line_id": "a36ea1bf-9e3c-4f88-a5db-2e431aefb629",
      "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "name": "Camisa do Flamengo Masculina I 26 Adidas",
      "quantity": 1,
      "unit_price": 30000,
      "total": 30000
    }
  ],
  "available_shipping": [
    {
      "id": "50000000-0000-0000-0000-000000000001",
      "name": "Entrega Padrão",
      "code": "standard",
      "cost": 0,
      "estimated_days": 10,
      "free_shipping": true
    }
  ],
  "available_payment": [
    { "id": "02000000-0000-0000-0000-000000000001", "name": "PIX", "code": "pix" },
    { "id": "1efe55b0-983b-4ff5-9892-d734986454cc", "name": "Cartão de Crédito", "code": "credit_card" }
  ]
}