API legada/Referência completa/Vitrine /api/storefront

Passos do checkout

Define o endereço e o documento, a forma de envio e a forma de pagamento de uma sessão de checkout.

Depois de abrir a sessão, três PUT a preenchem: endereço (com CPF ou CNPJ), frete e pagamento. A ordem importa: o frete depende do endereço, e o desconto do PIX depende do pagamento. Cada chamada devolve a sessão inteira, já com o total recalculado, e avança o step: address → shipping → payment → review.

Todas pedem ser o dono da sessão (JWT do cliente ou o mesmo X-Session-ID do visitante).

Endereço e documento

PUT/api/storefront/checkout/{sessionId}/addressCliente

Definir endereço de entrega e documento

Grava o endereço de entrega, o de cobrança (igual ao de entrega se omitido) e o documento fiscal. Calcula impostos e ajustes de preço por estado para o destino, e leva a sessão ao passo shipping.

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 empresa, a razão social inteira vai aqui.

last_namestring

Sobrenome. Opcional (vazio para empresa).

phonestring

Telefone de contato.

address_line1stringobrigatório

Logradouro.

address_line2string

Complemento.

numberstring

Número do imóvel. Algumas lojas exigem o número separado do logradouro (política de endereço, veja Erros).

districtstring

Bairro. Algumas lojas o exigem.

citystringobrigatório

Cidade.

statestringobrigatório

Sigla do estado (SP).

postal_codestringobrigatório

CEP com 8 dígitos, com ou sem hífen. 00000000 é recusado.

countrystringobrigatório

País (BR).

address_iduuid

Id de um endereço salvo do cliente, quando o endereço veio dele.

billing_addressobject

Endereço de cobrança, com os mesmos campos. Omitido: igual ao de entrega.

cpfstringobrigatório

CPF ou CNPJ do comprador, com ou sem pontuação (123.456.789-09). A resposta informa em document_type se foi lido como cpf ou cnpj.

Forma de envio

PUT/api/storefront/checkout/{sessionId}/shippingCliente

Escolher a forma de envio

Escolhe uma das opções de available_shipping do resumo. O servidor cota o frete sozinho para o destino; o valor entra em shipping_cost e no total. Leva a sessão ao passo payment.

Corpo da requisição

shipping_method_iduuidobrigatório

id da forma de envio, de available_shipping.

service_codestring

Serviço da transportadora quando a forma de envio expande várias opções (PAC, SEDEX). Vazio escolhe a única tarifa do método.

vendor_selectionsarray

Escolha uma forma por seller, para carrinhos com vários sellers que não têm um método em comum. Quando vem, substitui shipping_method_id e service_code.

vendor_idstringobrigatório

Id do seller, ou _marketplace para os itens da própria loja.

method_iduuidobrigatório

Forma de envio escolhida para esse seller.

service_codestring

Serviço da transportadora.

pickup_warehouse_iduuid

Retirada em loja: id do depósito. Quando vem, o frete do grupo é 0 e um agendamento de retirada é criado ao fechar o pedido.

delivery_slot_iduuid

Janela de retirada ou entrega escolhida.

shipping_costinteger

Aceito por compatibilidade e ignorado: o servidor sempre cota o frete.

Forma de pagamento

PUT/api/storefront/checkout/{sessionId}/paymentCliente

Escolher a forma de pagamento

Escolhe uma das opções de available_payment. Recalcula o total (desconto do PIX, acréscimo de parcelamento ou de plano faturado) e leva a sessão ao passo review. Nenhuma cobrança acontece aqui: o pagamento só começa ao fechar o pedido.

Corpo da requisição

payment_methodstringobrigatório

code da forma de pagamento, de available_payment (pix, credit_card...).

payment_profile_iduuid

Cartão salvo do cliente, no checkout de um clique.

invoiced_plan_iduuid

Plano de parcelas, obrigatório ao fechar quando a forma é boleto faturado.

Exemplo de requisição

bash

H='-H X-Session-ID:'"$VISITOR_ID"' -H Content-Type:application/json'

curl -X PUT "$BASE_URL/api/storefront/checkout/$SESSION_ID/address" $H -d '{
  "shipping_address": {
    "first_name": "Maria", "last_name": "Souza", "phone": "11999990000",
    "address_line1": "Avenida Paulista, 1000", "address_line2": "Apto 12",
    "number": "1000", "district": "Bela Vista",
    "city": "São Paulo", "state": "SP", "postal_code": "01310-100", "country": "BR"
  },
  "cpf": "123.456.789-09"
}'

curl -X PUT "$BASE_URL/api/storefront/checkout/$SESSION_ID/shipping" $H \
  -d '{"shipping_method_id":"50000000-0000-0000-0000-000000000001"}'

curl -X PUT "$BASE_URL/api/storefront/checkout/$SESSION_ID/payment" $H \
  -d '{"payment_method":"pix"}'

Resposta

200Sessão após o pagamento (reduzida)

json

{
  "id": "bcc7b882-448e-4b50-b870-41521b747889",
  "step": "review",
  "shipping_address": {
    "first_name": "Maria", "last_name": "Souza", "phone": "11999990000",
    "address_line1": "Avenida Paulista, 1000", "address_line2": "Apto 12",
    "number": "1000", "district": "Bela Vista",
    "city": "São Paulo", "state": "SP", "postal_code": "01310-100", "country": "BR"
  },
  "shipping_method_id": "50000000-0000-0000-0000-000000000001",
  "shipping_cost": 0,
  "payment_method": "pix",
  "payment_method_id": "02000000-0000-0000-0000-000000000001",
  "subtotal": 30000,
  "discount": 7500,
  "pix_discount": 1125,
  "tax": 0,
  "total": 21375,
  "cpf": "123.456.789-09",
  "document_type": "cpf",
  "promised_delivery_date": "2026-10-27",
  "promised_shipping_method": "Entrega Padrão"
}

A resposta é a sessão descrita em Iniciar checkout. Neste exemplo o total é subtotal - discount - pix_discount (30000 - 7500 - 1125 = 21375), porque o frete saiu grátis por promoção automática.

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error": "invalid request body"}`
400	Campo de endereço obrigatório ausente	`{"error": "invalid shipping address: first_name is required"}` (também `address_line1`, `city`, `state`, `postal_code`, `country`)
400	CEP brasileiro que não tem 8 dígitos ou é sentinela	mensagem do CEP inválido
400	Documento ausente ou inválido	`{"error": "cpf is required"}` ou `{"error": "invalid document (CPF/CNPJ): 123"}`
400	`shipping_method_id` ausente	`{"error": "shipping_method_id is required"}`
400	Forma de envio desconhecida	`{"error": "shipping method not found: <id>"}`
400	`payment_method` ausente	`{"error": "payment_method is required"}`
400	Forma de pagamento desconhecida, inativa ou fora do valor mínimo ou máximo	`{"error": "payment method not found: nope"}`, `payment method "x" is not active (status: D)` ou `order amount N is below the minimum M for payment method "x"`
403	Chave `sfk_` ou token `vat_` sem o escopo	`{"error": "missing_scope", "required": "..."}`
404	Sessão inexistente ou de outra pessoa	`{"error": "checkout session not found"}`
422	Política de endereço da loja recusou o endereço	`{"error": "address_number_required", "message": "...", "params": {...}}`

Em um carrinho só com produtos digitais (sem entrega), os campos de endereço não são conferidos.

Os códigos 422 de política de endereço são address_number_required, address_number_in_street, address_district_required e address_cep_mismatch. Só aparecem em lojas que ligaram a política.

Veja também

Passos do checkout

Define o endereço e o documento, a forma de envio e a forma de pagamento de uma sessão de checkout.

Todas pedem ser o dono da sessão (JWT do cliente ou o mesmo X-Session-ID do visitante).

Endereço e documento

PUT/api/storefront/checkout/{sessionId}/addressCliente

Definir endereço de entrega e documento

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 empresa, a razão social inteira vai aqui.

last_namestring

Sobrenome. Opcional (vazio para empresa).

phonestring

Telefone de contato.

address_line1stringobrigatório

Logradouro.

address_line2string

Complemento.

numberstring

Número do imóvel. Algumas lojas exigem o número separado do logradouro (política de endereço, veja Erros).

districtstring

Bairro. Algumas lojas o exigem.

citystringobrigatório

Cidade.

statestringobrigatório

Sigla do estado (SP).

postal_codestringobrigatório

CEP com 8 dígitos, com ou sem hífen. 00000000 é recusado.

countrystringobrigatório

País (BR).

address_iduuid

Id de um endereço salvo do cliente, quando o endereço veio dele.

billing_addressobject

Endereço de cobrança, com os mesmos campos. Omitido: igual ao de entrega.

cpfstringobrigatório

CPF ou CNPJ do comprador, com ou sem pontuação (123.456.789-09). A resposta informa em document_type se foi lido como cpf ou cnpj.

Forma de envio

PUT/api/storefront/checkout/{sessionId}/shippingCliente

Escolher a forma de envio

Escolhe uma das opções de available_shipping do resumo. O servidor cota o frete sozinho para o destino; o valor entra em shipping_cost e no total. Leva a sessão ao passo payment.

Corpo da requisição

shipping_method_iduuidobrigatório

id da forma de envio, de available_shipping.

service_codestring

Serviço da transportadora quando a forma de envio expande várias opções (PAC, SEDEX). Vazio escolhe a única tarifa do método.

vendor_selectionsarray

Escolha uma forma por seller, para carrinhos com vários sellers que não têm um método em comum. Quando vem, substitui shipping_method_id e service_code.

vendor_idstringobrigatório

Id do seller, ou _marketplace para os itens da própria loja.

method_iduuidobrigatório

Forma de envio escolhida para esse seller.

service_codestring

Serviço da transportadora.

pickup_warehouse_iduuid

Retirada em loja: id do depósito. Quando vem, o frete do grupo é 0 e um agendamento de retirada é criado ao fechar o pedido.

delivery_slot_iduuid

Janela de retirada ou entrega escolhida.

shipping_costinteger

Aceito por compatibilidade e ignorado: o servidor sempre cota o frete.

Forma de pagamento

PUT/api/storefront/checkout/{sessionId}/paymentCliente

Escolher a forma de pagamento

Corpo da requisição

payment_methodstringobrigatório

code da forma de pagamento, de available_payment (pix, credit_card...).

payment_profile_iduuid

Cartão salvo do cliente, no checkout de um clique.

invoiced_plan_iduuid

Plano de parcelas, obrigatório ao fechar quando a forma é boleto faturado.

Exemplo de requisição

bash

H='-H X-Session-ID:'"$VISITOR_ID"' -H Content-Type:application/json'

curl -X PUT "$BASE_URL/api/storefront/checkout/$SESSION_ID/address" $H -d '{
  "shipping_address": {
    "first_name": "Maria", "last_name": "Souza", "phone": "11999990000",
    "address_line1": "Avenida Paulista, 1000", "address_line2": "Apto 12",
    "number": "1000", "district": "Bela Vista",
    "city": "São Paulo", "state": "SP", "postal_code": "01310-100", "country": "BR"
  },
  "cpf": "123.456.789-09"
}'

curl -X PUT "$BASE_URL/api/storefront/checkout/$SESSION_ID/shipping" $H \
  -d '{"shipping_method_id":"50000000-0000-0000-0000-000000000001"}'

curl -X PUT "$BASE_URL/api/storefront/checkout/$SESSION_ID/payment" $H \
  -d '{"payment_method":"pix"}'

Resposta

200Sessão após o pagamento (reduzida)

json

{
  "id": "bcc7b882-448e-4b50-b870-41521b747889",
  "step": "review",
  "shipping_address": {
    "first_name": "Maria", "last_name": "Souza", "phone": "11999990000",
    "address_line1": "Avenida Paulista, 1000", "address_line2": "Apto 12",
    "number": "1000", "district": "Bela Vista",
    "city": "São Paulo", "state": "SP", "postal_code": "01310-100", "country": "BR"
  },
  "shipping_method_id": "50000000-0000-0000-0000-000000000001",
  "shipping_cost": 0,
  "payment_method": "pix",
  "payment_method_id": "02000000-0000-0000-0000-000000000001",
  "subtotal": 30000,
  "discount": 7500,
  "pix_discount": 1125,
  "tax": 0,
  "total": 21375,
  "cpf": "123.456.789-09",
  "document_type": "cpf",
  "promised_delivery_date": "2026-10-27",
  "promised_shipping_method": "Entrega Padrão"
}

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error": "invalid request body"}`
400	Campo de endereço obrigatório ausente	`{"error": "invalid shipping address: first_name is required"}` (também `address_line1`, `city`, `state`, `postal_code`, `country`)
400	CEP brasileiro que não tem 8 dígitos ou é sentinela	mensagem do CEP inválido
400	Documento ausente ou inválido	`{"error": "cpf is required"}` ou `{"error": "invalid document (CPF/CNPJ): 123"}`
400	`shipping_method_id` ausente	`{"error": "shipping_method_id is required"}`
400	Forma de envio desconhecida	`{"error": "shipping method not found: <id>"}`
400	`payment_method` ausente	`{"error": "payment_method is required"}`
400	Forma de pagamento desconhecida, inativa ou fora do valor mínimo ou máximo	`{"error": "payment method not found: nope"}`, `payment method "x" is not active (status: D)` ou `order amount N is below the minimum M for payment method "x"`
403	Chave `sfk_` ou token `vat_` sem o escopo	`{"error": "missing_scope", "required": "..."}`
404	Sessão inexistente ou de outra pessoa	`{"error": "checkout session not found"}`
422	Política de endereço da loja recusou o endereço	`{"error": "address_number_required", "message": "...", "params": {...}}`

Em um carrinho só com produtos digitais (sem entrega), os campos de endereço não são conferidos.