Checkout

O checkout transforma um carrinho em um pedido. Em vez de enviar tudo de uma vez, o comprador percorre uma sessão de checkout: você abre a sessão a partir do carrinho, grava o endereço, escolhe o frete e o pagamento, aplica descontos e, por fim, fecha o pedido. A cada passo a API recalcula os valores no servidor e devolve a sessão atualizada, então a tela sempre mostra o total que será cobrado.

Esta seção serve a qualquer front-end que monte o próprio checkout (site, app, quiosque). O checkout padrão da vitrine da Venddor usa exatamente estas rotas.

Como funciona

O campo step da sessão acompanha o andamento. Ele é informativo: avança sozinho quando você grava o endereço, o frete e o pagamento, e você pode chamar as etapas em outra ordem ou repeti-las.

1. Abra a sessão

   Iniciar o checkout com o cart_id. Visitantes informam também guest_email.

2. Grave endereço, frete e pagamento

   As três etapas em ordem. Chame GET /checkout/{sessionId} para saber quais fretes e pagamentos a loja oferece para este carrinho e endereço.

3. Aplique descontos, se houver

   Cupom e vale-presente.

4. Valide e feche

   Validar mostra os problemas sem criar nada. Fechar o pedido cria o pedido e esvazia o carrinho.

Conceitos-chave

Visitante e cliente logado

O checkout de visitante (guest checkout) pode ser desligado pela loja. A opção aparece como allow_guest_checkout nas configurações do checkout. Com ela desligada, abrir a sessão sem login devolve 403 guest checkout is not enabled. O visitante precisa informar guest_email; guest_name e guest_phone são opcionais.

O total é calculado pelo servidor

total = subtotal + frete + impostos acrescidos - descontos - desconto PIX - vale-presente + ajuste do meio de pagamento + juros do parcelamento. Cada etapa recalcula tudo. Os campos discount, catalog_discount, b2b_discount, state_discount e pix_discount detalham de onde vem o abatimento. state_discount pode ser negativo (o preço da região é maior que o do catálogo).

Pedido de vários sellers

Se o carrinho tem produtos de mais de um seller (lojista), o fechamento cria um pedido pai e um sub-pedido por seller. O frete pode ser escolhido por seller com vendor_selections (As três etapas).

Erros em português

Os erros desta seção saem em dois formatos. Rotas de etapa respondem {"error": "texto em inglês"}. O fechamento do pedido responde códigos estáveis em inglês (price_changed, otp_required) e, quando há uma frase para o comprador, a message vem em português e assim permanece nas duas línguas desta documentação.

Rotas

Erros comuns

• Mandar o X-Session-ID errado. O visitante que abriu a sessão com um identificador e consulta com outro recebe 404 checkout session not found. Reuse o mesmo valor do carrinho.
• Esquecer o CPF. O endereço exige cpf (CPF ou CNPJ válido), mesmo para visitante. Sem ele: 400 cpf is required.
• Tentar fechar sem as três etapas. Faltando endereço, frete ou pagamento o fechamento responde 400 com shipping address is required, shipping method is required ou payment method is required. Carrinho só digital dispensa o frete.
• Enviar o valor do frete. shipping_cost no corpo é descartado: o servidor cota o frete de novo. Use o id devolvido em available_shipping.
• Fechar sem Idempotency-Key. Um segundo clique durante o processamento pode devolver 409 order_in_progress ou cart_already_ordered. Gere uma chave por tentativa de compra e reaproveite em reenvios.
• Deixar a sessão envelhecer. Depois de 2 horas a sessão some e as rotas devolvem 404. Abra outra a partir do mesmo carrinho.

Próximos passos