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

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"
}'

Resposta

201Sessão criada

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"
}

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

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

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

bash

curl "$BASE_URL/api/v1/storefront/checkout/$CHECKOUT_ID" \
  -H "X-Session-ID: $SESSION_ID"

Resposta

200Sessão com opções

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" }
  ]
}

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

Status	Quando	Corpo
404	Sessão inexistente, expirada, de outra loja ou de outro dono	`{"error":"checkout session not found"}`

Veja também

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.

Iniciar o checkout

POST/api/v1/storefront/checkoutAutenticada

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

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

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"
}'

Resposta

201Sessão criada

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"
}

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

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

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

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

bash

curl "$BASE_URL/api/v1/storefront/checkout/$CHECKOUT_ID" \
  -H "X-Session-ID: $SESSION_ID"

Resposta

200Sessão com opções

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" }
  ]
}

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

Status	Quando	Corpo
404	Sessão inexistente, expirada, de outra loja ou de outro dono	`{"error":"checkout session not found"}`