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

Endereço, frete e pagamento

As três etapas obrigatórias da sessão de checkout, com os campos do endereço, a escolha do frete e a escolha da forma de pagamento.

Depois de abrir a sessão, grave três escolhas do comprador. Cada chamada é um PUT que substitui a escolha anterior daquela etapa e devolve a sessão inteira, com step, descontos e total recalculados pelo servidor. Você pode repetir uma etapa quantas vezes quiser (por exemplo, trocar o frete) antes de fechar o pedido.

A ordem natural é endereço, frete, pagamento: o endereço define quais fretes existem, e o frete e o pagamento mudam o total (frete, desconto PIX, juros). Um carrinho só com itens digitais não tem frete: depois do endereço a sessão vai direto para payment.

Gravar o endereço

PUT/api/v1/storefront/checkout/{sessionId}/addressAutenticada

Define o endereço de entrega e de cobrança e o documento fiscal do comprador

Grava o endereço de entrega, o de cobrança e o CPF ou CNPJ do comprador. Se você não mandar billing_address, a cobrança usa o mesmo endereço da entrega. A API também recalcula impostos e reavalia descontos que dependem do estado de destino (preço regional). Se um cupom aplicado deixa de valer com o novo endereço, ele é removido da sessão sem aviso, e o frete já escolhido é cotado de novo.

Parâmetros de caminho

sessionIduuidobrigatório
Id da sessão.

Corpo da requisição

shipping_addressobjectobrigatório

Endereço de entrega.

first_namestringobrigatório
Nome do destinatário. Para pessoa jurídica, a razão social inteira vai aqui.
last_namestring
Sobrenome. Opcional (vazio para empresa).
phonestring
Telefone de contato.
address_line1stringobrigatório
Rua e, se a loja não exigir campo próprio, o número.
address_line2string
Número ou complemento. Veja a regra de número abaixo.
numberstring
Número do imóvel, quando o seu formulário tem campo separado.
districtstring
Bairro. Obrigatório quando a loja ativa require_address_district.
citystringobrigatório
Cidade.
statestringobrigatório
UF com 2 letras (SP).
postal_codestringobrigatório
CEP, com ou sem hífen. Precisa ter 8 dígitos e não pode começar com 00 nem ser 99999999.
countrystringobrigatório
País, BR para o Brasil.
address_iduuid
Id de um endereço salvo do cliente. Opcional. Ajuda a cotar frete de áreas desenhadas no mapa.
billing_addressobject
Endereço de cobrança, com os mesmos campos. Omita para usar o de entrega.
cpfstringobrigatório
CPF ou CNPJ do comprador, com ou sem pontuação. A API valida os dígitos e deduz document_type.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/storefront/checkout/$CHECKOUT_ID/address" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "shipping_address": {
    "first_name": "Maria",
    "last_name": "Souza",
    "phone": "11987654321",
    "address_line1": "Av Paulista, 1000",
    "address_line2": "Apto 12",
    "district": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01310-100",
    "country": "BR"
  },
  "cpf": "123.456.789-09"
}'

Resposta

200Endereço gravado
json
{
  "id": "f9f26cde-bc64-4d49-ab14-e3fe35971432",
  "cart_id": "caad0bcd-177e-47cc-a02a-0ad63a47ee21",
  "is_guest": true,
  "step": "shipping",
  "shipping_address": {
    "first_name": "Maria",
    "last_name": "Souza",
    "phone": "11987654321",
    "address_line1": "Av Paulista, 1000",
    "address_line2": "Apto 12",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01310-100",
    "country": "BR",
    "district": "Bela Vista"
  },
  "billing_address": { "first_name": "Maria", "address_line1": "Av Paulista, 1000", "postal_code": "01310-100" },
  "shipping_method_id": null,
  "shipping_cost": 0,
  "subtotal": 30000,
  "discount": 7500,
  "tax": 0,
  "total": 22500,
  "cpf": "123.456.789-09",
  "document_type": "cpf"
}

A resposta é a sessão completa (campos descritos em Iniciar e ler); acima ela aparece encurtada. Quando a loja calcula impostos, vem também tax_breakdown com ICMS, ISS, IPI, PIS e COFINS por produto.

Erros

StatusQuandoCorpo
400Campo obrigatório vazio{"error":"invalid shipping address: address_line1 is required"} (idem first_name, city, state, postal_code, country)
400CEP inválido{"error":"invalid shipping address: ..."}
400Sem cpf{"error":"cpf is required"}
400CPF/CNPJ com dígitos inválidos{"error":"invalid document (CPF/CNPJ): 111"}
404Sessão inexistente ou de outro dono{"error":"checkout session not found"}
422A loja ativou a política de endereço e o endereço a viola{"error":"address_number_required","message":"Informe o número do endereço no campo Número (use \"S/N\" se o imóvel não tiver número)."}

Os códigos 422 possíveis são address_number_required, address_number_in_street (o número está colado na rua e precisa ir para o campo de número), address_district_required e address_cep_mismatch (o CEP pertence a outra cidade, UF ou bairro). A message vem em português. Em address_number_in_street e address_cep_mismatch há também params com os detalhes para você montar a sua mensagem.

Política de endereço é opcional por loja

Número obrigatório, bairro obrigatório e conferência do CEP estão desligados por padrão e são ligados nas configurações da loja (require_address_number, require_address_district, cep_consistency em Configurações do checkout). Leia essas chaves antes e valide no seu formulário. A política vale só para a entrega física: pedido apenas digital é isento.

Escolher o frete

PUT/api/v1/storefront/checkout/{sessionId}/shippingAutenticada

Escolhe a forma de envio

Escolhe um dos fretes de available_shipping. O servidor cota o frete de novo com o endereço e os itens da sessão e grava o custo real. Se o cupom aplicado dá frete grátis para esse método, ou se a retirada em loja é escolhida, o custo vira 0. A API também calcula a data prometida de entrega (promised_delivery_date, YYYY-MM-DD) quando a loja usa janela de entrega.

Exige que o endereço já tenha sido gravado.

Parâmetros de caminho

sessionIduuidobrigatório
Id da sessão.

Corpo da requisição

shipping_method_iduuidobrigatório
Id do frete (available_shipping[].id). Obrigatório, a menos que use vendor_selections.
service_codestring
Serviço da transportadora (PAC, SEDEX...) quando o método é um agregador que oferece vários. Obrigatório quando o método é ambíguo.
vendor_selectionsarray

Um frete por seller, para sacolas de vários sellers sem frete em comum. Quando enviado, substitui shipping_method_id e service_code. É preciso um item para cada seller do carrinho, sem repetir.

vendor_idstringobrigatório
Id do seller (lojista), ou _marketplace para os itens da própria loja.
method_iduuidobrigatório
Frete escolhido para esse seller.
service_codestring
Serviço da transportadora, se aplicável.
pickup_warehouse_iduuid
Escolhe retirada em loja (BOPIS) neste depósito. O frete vira 0 e uma retirada é registrada ao fechar o pedido. Não vale junto com vendor_selections.
delivery_slot_iduuid
Horário de retirada, quando a loja usa janelas.
shipping_costinteger
Ignorado. O servidor sempre usa o valor que ele mesmo cotou.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/storefront/checkout/$CHECKOUT_ID/shipping" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "shipping_method_id": "50000000-0000-0000-0000-000000000001"
}'

Resposta

200Frete gravado
json
{
  "id": "f9f26cde-bc64-4d49-ab14-e3fe35971432",
  "step": "payment",
  "shipping_method_id": "50000000-0000-0000-0000-000000000001",
  "shipping_cost": 0,
  "promised_delivery_date": "2026-10-27",
  "promised_shipping_method": "Entrega Padrão",
  "subtotal": 30000,
  "discount": 7500,
  "total": 22500
}

Campos novos na sessão

shipping_method_iduuid
Frete gravado.
shipping_costinteger
Custo do frete em centavos, cotado pelo servidor.
promised_delivery_datestring
Data prometida de entrega, YYYY-MM-DD. Ausente quando a loja não usa janela de entrega. É congelada no pedido.
promised_shipping_methodstring
Nome do frete no momento da escolha.
shipping_service_codestring
Serviço da transportadora escolhido, quando houver.

Erros

StatusQuandoCorpo
400Sem shipping_method_id{"error":"shipping_method_id is required"}
400Frete que não existe{"error":"shipping method not found: 0000..."}
400Frete grátis acima de um valor e o pedido não chegou nele{"error":"shipping method not available for this order total: ..."}
400Endereço ainda não gravado{"error":"shipping_requote_required: shipping address is required"}
400O frete não atende o endereço ou o serviço sumiu{"error":"shipping_requote_required: selected shipping method or service is no longer available"}
400Método com vários serviços sem service_code{"error":"shipping_requote_required: service_code is required for ambiguous shipping method"}
404Sessão inexistente ou de outro dono{"error":"checkout session not found"}
Prefixo shipping_requote_required

Erro que começa com shipping_requote_required: significa "o frete precisa ser escolhido de novo". Releia GET /checkout/{sessionId}, mostre as opções atuais e peça a escolha outra vez. No fechamento do pedido o mesmo problema vira 409 shipping_requote_required.

Escolher o pagamento

PUT/api/v1/storefront/checkout/{sessionId}/paymentAutenticada

Escolhe a forma de pagamento

Escolhe a forma de pagamento pelo code listado em available_payment. A API confere se ela está ativa, se vale para os sellers e o grupo do comprador, e se o total respeita o mínimo e o máximo da forma. Em seguida recalcula: PIX ganha o desconto da loja (pix_discount), formas com taxa ou desconto próprio entram em payment_adjustment, e o plano de Boleto Faturado soma o acréscimo do plano.

Esta rota não cobra nada. Ela só registra a escolha; a cobrança acontece no fechamento do pedido.

Parâmetros de caminho

sessionIduuidobrigatório
Id da sessão.

Corpo da requisição

payment_methodstringobrigatório
Código da forma de pagamento (available_payment[].code), por exemplo pix ou credit_card.
invoiced_plan_iduuid
Plano de parcelas do Boleto Faturado (pagamento B2B a prazo). Exigido ao fechar o pedido quando a forma é Boleto Faturado.
payment_profile_iduuid
Cartão salvo do cliente, para compra expressa com um clique.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/storefront/checkout/$CHECKOUT_ID/payment" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "payment_method": "pix"
}'

Resposta

200Pagamento gravado
json
{
  "id": "f9f26cde-bc64-4d49-ab14-e3fe35971432",
  "step": "review",
  "payment_method": "pix",
  "payment_method_id": "02000000-0000-0000-0000-000000000001",
  "subtotal": 30000,
  "discount": 7500,
  "pix_discount": 1125,
  "total": 21375
}

Campos novos na sessão

payment_methodstring
Código da forma escolhida.
payment_method_iduuid
Id da forma no cadastro da loja.
pix_discountinteger
Desconto de PIX em centavos (percentual configurado pela loja sobre o valor a pagar).
payment_adjustmentinteger
Taxa (positiva) ou desconto (negativa) próprio da forma de pagamento, em centavos. Ausente quando zero.
invoiced_plan_surchargeinteger
Acréscimo do plano do Boleto Faturado, em centavos. Ausente quando zero.

Erros

StatusQuandoCorpo
400Sem payment_method{"error":"payment_method is required"}
400Código que não existe ou não vale para este carrinho{"error":"payment method not found: nope"}
400Forma desativada{"error":"payment method \"pix\" is not active (status: D)"}
400Total abaixo do mínimo da forma{"error":"order amount 900 is below the minimum 1000 for payment method \"pix\""}
400Total acima do máximo da forma{"error":"order amount ... exceeds the maximum ... for payment method \"...\""}
400Plano de Boleto Faturado inexistente ou desativado{"error":"invoiced installment plan \"...\" not found for payment method \"...\""}
404Sessão inexistente ou de outro dono{"error":"checkout session not found"}
Total mostrado ao comprador

Chame o PUT .../payment assim que o comprador trocar de forma de pagamento e mostre o total devolvido. É o único jeito de exibir o valor com o desconto de PIX ou a taxa da forma já aplicados.

Veja também

  • Iniciar e ler o checkout
  • Cupom e vale-presente
  • Validar e fechar o pedido
  • Configurações do checkout
Anterior
Iniciar e ler o checkout
Próxima
Cupom e vale-presente no checkout
Nesta página
  • Gravar o endereço
  • Exemplo de requisição
  • Resposta
  • Erros
  • Escolher o frete
  • Exemplo de requisição
  • Resposta
  • Erros
  • Escolher o pagamento
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também