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

Iniciar checkout

Abre uma sessão de checkout a partir de um carrinho e lê o resumo da sessão com as opções de frete e pagamento.

O checkout é o caminho entre um carrinho cheio e um pedido. Ele roda numa sessão: um registro temporário que guarda o endereço, o frete, a forma de pagamento e os descontos do cliente, e recalcula o total a cada passo. Você abre a sessão com o id de um carrinho e depois a vai preenchendo (passos do checkout).

O carrinho em si é criado e alterado pela loja ou pelo app do cliente (visitantes são identificados pelo cabeçalho X-Session-ID; clientes logados, pelo JWT). É dele que sai o cart_id que você usa aqui.

Abrir a sessão

POST/api/storefront/checkoutCliente

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

Vale para cliente logado e para visitante. Cliente logado: o carrinho precisa ser dele. Visitante: o carrinho precisa ter sido criado com o mesmo X-Session-ID desta chamada, e o corpo precisa trazer guest_email.

Corpo da requisição

cart_iduuidobrigatório

Id do carrinho.

guest_emailstring

E-mail do comprador. Obrigatório para visitante (sem JWT); ignorado quando há cliente logado.

guest_namestring

Nome do visitante.

guest_phonestring

Telefone do visitante.

Cabeçalhos

Authorizationstring

Bearer <jwt> do cliente. Para visitante, omita.

X-Session-IDstring

Id de sessão do visitante, o mesmo do carrinho. Obrigatório para visitante.

X-API-Keystring

Opcional. Chave sfk_... com o escopo storefront:write. Token de app: Authorization: Bearer vat_... com write_orders.

Ler o resumo

GET/api/storefront/checkout/{sessionId}Cliente

Ler o resumo da sessão com opções de frete e pagamento

Devolve a sessão, as linhas do carrinho e as opções que o cliente pode escolher agora. Use depois de cada passo para mostrar o total atualizado.

Parâmetros de caminho

sessionIduuidobrigatório

Id da sessão (id da resposta do POST).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/storefront/checkout" \
  -H "X-Session-ID: $VISITOR_ID" \
  -H "Content-Type: application/json" \
  -d '{"cart_id":"1654b5de-3e96-44a5-bd77-2eaa82ccabf2","guest_email":"maria@example.com","guest_name":"Maria Souza","guest_phone":"11999990000"}'

curl "$BASE_URL/api/storefront/checkout/$SESSION_ID" -H "X-Session-ID: $VISITOR_ID"

Resposta

201Sessão criada

json

{
  "id": "bcc7b882-448e-4b50-b870-41521b747889",
  "cart_id": "1654b5de-3e96-44a5-bd77-2eaa82ccabf2",
  "user_id": "",
  "is_guest": true,
  "guest_email": "maria@example.com",
  "guest_name": "Maria Souza",
  "guest_phone": "11999990000",
  "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-11T21:20:06.765516Z",
  "updated_at": "2026-10-11T21:20:06.765516Z"
}

200Resumo da sessão (itens e opções reduzidos)

json

{
  "session": { "id": "bcc7b882-448e-4b50-b870-41521b747889", "step": "address", "total": 22500 },
  "items": [
    {
      "line_id": "42a06d8b-e97d-403a-899b-b76bf3bd0c73",
      "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "name": "Camisa do Flamengo Masculina I 26 Adidas",
      "sku": "FLA-I-26",
      "unit_price": 30000,
      "list_price": 44990,
      "quantity": 1,
      "total": 30000
    }
  ],
  "available_shipping": [
    { "id": "50000000-0000-0000-0000-000000000001", "name": "Entrega Padrão", "code": "standard", "cost": 1000, "estimated_days": 10, "free_shipping": false }
  ],
  "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 sessão

iduuid

Id da sessão. Use em todas as chamadas seguintes.

cart_iduuid

Carrinho de origem.

user_idstring

Cliente logado, ou vazio para visitante.

is_guestboolean

true para visitante.

stepstring

addressshippingpaymentreview

Passo em que a sessão está. Avança sozinho: address, depois shipping, payment e review.

shipping_addressobject|null

Endereço de entrega, preenchido no passo de endereço.

billing_addressobject|null

Endereço de cobrança (por padrão igual ao de entrega).

shipping_method_iduuid|null

Forma de envio escolhida.

shipping_costinteger

Frete em centavos.

payment_methodstring|null

Código da forma de pagamento escolhida.

subtotalinteger

Soma das linhas, em centavos, antes de descontos e frete.

discountinteger

Desconto total de pedido em centavos: desconto de catálogo + contrato B2B + ajuste por estado + cupom.

catalog_discountinteger

Parte do desconto que vem de promoções de catálogo.

b2b_discountinteger

Parte que vem da tabela de preços por faixa de contrato B2B.

state_discountinteger

Ajuste de preço por estado de destino. Pode ser negativo (preço regional maior). Fica 0 até o endereço ser informado.

pix_discountinteger

Desconto da forma de pagamento PIX, em centavos.

taxinteger

Imposto calculado, em centavos. Só entra no total quando tax_included é false.

tax_includedboolean

true quando os preços da loja já incluem imposto.

totalinteger

Total a pagar, em centavos. O servidor recalcula a cada passo; não some no cliente.

coupon_codestring|null

Cupom aplicado.

gift_cert_amountinteger

Valor abatido por vale-presente, em centavos.

cpfstring

CPF ou CNPJ informado no passo de endereço. document_type diz qual: cpf ou cnpj.

free_shippingboolean

true se um cupom concedeu frete grátis. auto_free_shipping indica frete grátis por promoção automática.

promised_delivery_datestring

Data prometida de entrega (YYYY-MM-DD), calculada ao escolher o frete, quando a loja usa janelas de entrega.

available_shippingarray

Opções de frete: id, name, code, cost (centavos), estimated_days, free_shipping, e service_code quando é um serviço de transportadora (PAC, SEDEX...).

available_paymentarray

Formas de pagamento disponíveis: id, name, code. Use o code no passo de pagamento.

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error": "invalid request body"}`
400	Visitante sem `guest_email`	`{"error": "guest_email is required for guest checkout"}`
400	Outra regra de negócio recusada	`{"error": "<mensagem>"}`
403	Chave `sfk_` ou token `vat_` sem o escopo (`storefront:write` ou `write_orders`)	`{"error": "missing_scope", "required": "..."}`
403	Carrinho vinculado a outro cliente registrado	`{"error": "you do not have permission to checkout this cart"}`
403	Loja com compra de visitante desligada	`{"error": "guest checkout is not enabled"}`
404	Carrinho inexistente ou que não é seu (também para `X-Session-ID` diferente)	`{"error": "cart not found"}`
404	`GET` de sessão que não existe ou é de outra pessoa	`{"error": "checkout session not found"}`

Veja também

Iniciar checkout

Abre uma sessão de checkout a partir de um carrinho e lê o resumo da sessão com as opções de frete e pagamento.

Abrir a sessão

POST/api/storefront/checkoutCliente

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

Corpo da requisição

cart_iduuidobrigatório

Id do carrinho.

guest_emailstring

E-mail do comprador. Obrigatório para visitante (sem JWT); ignorado quando há cliente logado.

guest_namestring

Nome do visitante.

guest_phonestring

Telefone do visitante.

Cabeçalhos

Authorizationstring

Bearer <jwt> do cliente. Para visitante, omita.

X-Session-IDstring

Id de sessão do visitante, o mesmo do carrinho. Obrigatório para visitante.

X-API-Keystring

Opcional. Chave sfk_... com o escopo storefront:write. Token de app: Authorization: Bearer vat_... com write_orders.

Ler o resumo

GET/api/storefront/checkout/{sessionId}Cliente

Ler o resumo da sessão com opções de frete e pagamento

Devolve a sessão, as linhas do carrinho e as opções que o cliente pode escolher agora. Use depois de cada passo para mostrar o total atualizado.

Parâmetros de caminho

sessionIduuidobrigatório

Id da sessão (id da resposta do POST).

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/storefront/checkout" \
  -H "X-Session-ID: $VISITOR_ID" \
  -H "Content-Type: application/json" \
  -d '{"cart_id":"1654b5de-3e96-44a5-bd77-2eaa82ccabf2","guest_email":"maria@example.com","guest_name":"Maria Souza","guest_phone":"11999990000"}'

curl "$BASE_URL/api/storefront/checkout/$SESSION_ID" -H "X-Session-ID: $VISITOR_ID"

Resposta

201Sessão criada

json

{
  "id": "bcc7b882-448e-4b50-b870-41521b747889",
  "cart_id": "1654b5de-3e96-44a5-bd77-2eaa82ccabf2",
  "user_id": "",
  "is_guest": true,
  "guest_email": "maria@example.com",
  "guest_name": "Maria Souza",
  "guest_phone": "11999990000",
  "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-11T21:20:06.765516Z",
  "updated_at": "2026-10-11T21:20:06.765516Z"
}

200Resumo da sessão (itens e opções reduzidos)

json

{
  "session": { "id": "bcc7b882-448e-4b50-b870-41521b747889", "step": "address", "total": 22500 },
  "items": [
    {
      "line_id": "42a06d8b-e97d-403a-899b-b76bf3bd0c73",
      "product_id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "name": "Camisa do Flamengo Masculina I 26 Adidas",
      "sku": "FLA-I-26",
      "unit_price": 30000,
      "list_price": 44990,
      "quantity": 1,
      "total": 30000
    }
  ],
  "available_shipping": [
    { "id": "50000000-0000-0000-0000-000000000001", "name": "Entrega Padrão", "code": "standard", "cost": 1000, "estimated_days": 10, "free_shipping": false }
  ],
  "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 sessão

iduuid

Id da sessão. Use em todas as chamadas seguintes.

cart_iduuid

Carrinho de origem.

user_idstring

Cliente logado, ou vazio para visitante.

is_guestboolean

true para visitante.

stepstring

addressshippingpaymentreview

Passo em que a sessão está. Avança sozinho: address, depois shipping, payment e review.

shipping_addressobject|null

Endereço de entrega, preenchido no passo de endereço.

billing_addressobject|null

Endereço de cobrança (por padrão igual ao de entrega).

shipping_method_iduuid|null

Forma de envio escolhida.

shipping_costinteger

Frete em centavos.

payment_methodstring|null

Código da forma de pagamento escolhida.

subtotalinteger

Soma das linhas, em centavos, antes de descontos e frete.

discountinteger

Desconto total de pedido em centavos: desconto de catálogo + contrato B2B + ajuste por estado + cupom.

catalog_discountinteger

Parte do desconto que vem de promoções de catálogo.

b2b_discountinteger

Parte que vem da tabela de preços por faixa de contrato B2B.

state_discountinteger

Ajuste de preço por estado de destino. Pode ser negativo (preço regional maior). Fica 0 até o endereço ser informado.

pix_discountinteger

Desconto da forma de pagamento PIX, em centavos.

taxinteger

Imposto calculado, em centavos. Só entra no total quando tax_included é false.

tax_includedboolean

true quando os preços da loja já incluem imposto.

totalinteger

Total a pagar, em centavos. O servidor recalcula a cada passo; não some no cliente.

coupon_codestring|null

Cupom aplicado.

gift_cert_amountinteger

Valor abatido por vale-presente, em centavos.

cpfstring

CPF ou CNPJ informado no passo de endereço. document_type diz qual: cpf ou cnpj.

free_shippingboolean

true se um cupom concedeu frete grátis. auto_free_shipping indica frete grátis por promoção automática.

promised_delivery_datestring

Data prometida de entrega (YYYY-MM-DD), calculada ao escolher o frete, quando a loja usa janelas de entrega.

available_shippingarray

Opções de frete: id, name, code, cost (centavos), estimated_days, free_shipping, e service_code quando é um serviço de transportadora (PAC, SEDEX...).

available_paymentarray

Formas de pagamento disponíveis: id, name, code. Use o code no passo de pagamento.

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error": "invalid request body"}`
400	Visitante sem `guest_email`	`{"error": "guest_email is required for guest checkout"}`
400	Outra regra de negócio recusada	`{"error": "<mensagem>"}`
403	Chave `sfk_` ou token `vat_` sem o escopo (`storefront:write` ou `write_orders`)	`{"error": "missing_scope", "required": "..."}`
403	Carrinho vinculado a outro cliente registrado	`{"error": "you do not have permission to checkout this cart"}`
403	Loja com compra de visitante desligada	`{"error": "guest checkout is not enabled"}`
404	Carrinho inexistente ou que não é seu (também para `X-Session-ID` diferente)	`{"error": "cart not found"}`
404	`GET` de sessão que não existe ou é de outra pessoa	`{"error": "checkout session not found"}`