Sacola e checkout da mini-loja

Como a sacola e o checkout da mini-loja do WhatsApp funcionam, em que ordem chamar as rotas e o mapa de todas elas.

A sacola (o carrinho) da mini-loja pertence ao token: ela acompanha o visitante ou o cliente entre o WhatsApp e o navegador. Estas rotas montam a sacola, aplicam desconto, escolhem endereço e entrega, conferem o total e fecham o pedido. O mesmo pedido pode ser pago por Pix, boleto, cartão online ou forma offline, conforme as formas que a loja configurou.

Pontos-chave

O servidor é a fonte do valor. O frete, o desconto de Pix, os impostos e o total são sempre recalculados no servidor. O que o navegador manda (shipping_choice, expected_total_cents) é conferido, nunca usado como preço.
Total que mudou é erro, não surpresa. Se você manda expected_total_cents no checkout e o total real for outro, a resposta é 409 checkout_total_changed com os totais novos. Mostre ao cliente e peça nova confirmação.
Pagar só parte da sacola. shipping, totals, validate e checkout aceitam line_ids, os itens marcados. Só eles são cotados, validados e pedidos; o resto fica na sacola.
O cartão online é cobrado antes do pedido existir. Se o cartão for recusado, nenhum pedido é criado e a sacola continua intacta.
Dinheiro em centavos, ids UUID. Os textos message já vêm em português para o cliente.
Cada rota exige o token da mini-loja no caminho. Visitante precisa que a loja permita comprar sem conta (allow_guest_checkout); senão responde 403 account_required.

Como funciona

Adicionar itens→Endereço→Frete→Totais e validação→Pagamento→Pedido

Montar a sacola
POST /cart/{token}/items adiciona produtos (veja Variação e frete para produtos com escolha); PATCH altera quantidades. A resposta é sempre a sacola inteira já recalculada.
Descontos
Cupom e cashback reduzem o total. Promoções automáticas da loja já aparecem na sacola (cart_promotions).
Endereço e frete
O cliente informa ou escolhe um endereço salvo. Com o CEP, POST /cart/{token}/shipping lista as opções de entrega.
Totais e validação
POST /cart/{token}/totals mostra o total exato com frete, impostos e desconto da forma de pagamento. POST /cart/{token}/validate confere exigências (idade, CNPJ).
Fechar o pedido
POST /cart/{token}/checkout cria o pedido e devolve como pagar (Pix, boleto, cartão). Depois, acompanhe em Pedidos.

Conceitos-chave

A sacola e suas linhas

A sacola tem linhas; cada linha tem um item_id próprio, estável até a linha sair. Use o item_id (não o product_id) para alterar ou remover, porque o mesmo produto pode aparecer em linhas diferentes (variações, opções, observações). A resposta de toda rota de sacola é a sacola completa, então você não precisa reler depois.

Marca na linha	Significa
`unavailable: true`	O produto deixou de ser vendido. A linha continua visível para o cliente poder removê-la, mas não pode ser pedida.
`stock_status`	`ok`, `limited` (estoque menor que a quantidade) ou `out`. Com `limited` e `out`, `available_qty` diz quanto dá.
`is_gift: true`	Brinde que a sacola concedeu. Acompanha os itens que dão direito a ele e não é marcado sozinho.
`bundle_id`	A linha veio de um combo "compre junto" e divide o desconto do combo. Combo é vendido inteiro ou nenhum.
`pending_choices`	Falta uma opção obrigatória (item entrou pelos favoritos). O checkout recusa até resolver.

Pedido mínimo, frete grátis e promoções

min_order_cents na sacola é o mínimo do destino (a loja pode ter um mínimo geral e outro por região). cart_promotions lista as promoções automáticas aplicadas e cart_promotion_discount_cents o desconto delas. Atenção: total_cents da sacola não desconta cupom nem promoção; o valor a pagar é total_cents menos cart_promotion_discount_cents menos discount_cents (cupom). O total real do pedido sai de /totals.

Conta e documento

Nas lojas que exigem conta, o checkout recusa quem não está identificado. O documento (CPF ou CNPJ) é sempre obrigatório no corpo do checkout e validado pelos dígitos; sem ele a resposta é 422 invalid_document.

Horário e loja fechada

Fora do horário, o checkout responde 409 store_closed, exceto nas lojas que aceitam pedido fechadas (allow_orders_closed).

Endpoints

Método	Rota	O que faz	Página
GET	`/api/v1/storefront/wa-coex/cart/{token}`	Lê a sacola	Ler e adicionar à sacola
POST	`/api/v1/storefront/wa-coex/cart/{token}/items`	Adiciona um produto	Ler e adicionar à sacola
POST	`/api/v1/storefront/wa-coex/cart/{token}/combo`	Adiciona um combo	Ler e adicionar à sacola
PATCH	`/api/v1/storefront/wa-coex/cart/{token}/items/{itemID}`	Altera a quantidade	Alterar itens
PUT	`/api/v1/storefront/wa-coex/cart/{token}/items/{itemID}/configuration`	Troca variação, opções e quantidade	Alterar itens
DELETE	`/api/v1/storefront/wa-coex/cart/{token}/items/{itemID}`	Remove a linha	Alterar itens
POST	`/api/v1/storefront/wa-coex/cart/{token}/coupon`	Aplica um cupom	Cupom e cashback
DELETE	`/api/v1/storefront/wa-coex/cart/{token}/coupon`	Remove o cupom	Cupom e cashback
GET	`/api/v1/storefront/wa-coex/cashback/{token}`	Saldo e uso do cashback	Cupom e cashback
POST	`/api/v1/storefront/wa-coex/cashback/{token}`	Usa o cashback	Cupom e cashback
DELETE	`/api/v1/storefront/wa-coex/cashback/{token}`	Deixa de usar o cashback	Cupom e cashback
GET	`/api/v1/storefront/wa-coex/addresses/{token}`	Lista os endereços salvos	Endereços
POST	`/api/v1/storefront/wa-coex/addresses/{token}`	Salva um endereço	Endereços
DELETE	`/api/v1/storefront/wa-coex/addresses/{token}/{addressID}`	Apaga um endereço	Endereços
POST	`/api/v1/storefront/wa-coex/cart/{token}/shipping`	Cota o frete para um CEP	Frete e totais
POST	`/api/v1/storefront/wa-coex/cart/{token}/totals`	Calcula o total exato	Frete e totais
POST	`/api/v1/storefront/wa-coex/cart/{token}/validate`	Confere exigências do pedido	Frete e totais
GET	`/api/v1/storefront/wa-coex/cart/{token}/sales-reps`	Consultores para escolher	Frete e totais
GET	`/api/v1/storefront/wa-coex/payments/{token}/eligible`	Formas de pagamento disponíveis	Frete e totais
POST	`/api/v1/storefront/wa-coex/cart/{token}/checkout`	Cria o pedido	Fechar o pedido
GET	`/api/v1/storefront/wa-coex/cart/{token}/card-tokenization`	Chave pública para tokenizar o cartão	Pagar com cartão
GET	`/api/v1/storefront/wa-coex/pay/{token}/card-options`	Parcelas do cartão de um pedido	Pagar com cartão
POST	`/api/v1/storefront/wa-coex/pay/{token}/card`	Cobra o cartão de um pedido existente	Pagar com cartão
GET	`/api/v1/storefront/wa-coex/pay/{token}/status/{orderID}`	Consulta se o pagamento do pedido caiu	Pagamento do pedido
GET	`/api/v1/storefront/wa-coex/pay/{token}/cards`	Lista os cartões salvos	Cartões salvos
DELETE	`/api/v1/storefront/wa-coex/pay/{token}/cards/{cardID}`	Apaga um cartão salvo	Cartões salvos

Erros comuns

Alterar pelo product_id. Alterar e remover usam o item_id da linha. O product_id só funciona quando o produto aparece em uma linha única.
Calcular o total no cliente. Some total_cents - cart_promotion_discount_cents - discount_cents só para exibir. Para cobrar, use /totals; o checkout recalcula de qualquer jeito.
Mandar um shipping_choice antigo. Se o CEP ou a sacola mudou, a escolha deixa de existir na cotação e o checkout responde 409 invalid_shipping_choice. Recote e peça nova escolha.
Esquecer o documento. cpf é obrigatório e validado, mesmo para cliente que já tem conta.
Enviar o número do cartão para a Pagar.me. Quando o gateway é a Pagar.me, o cartão novo precisa ser tokenizado no navegador (card_token); número e CVV no corpo são recusados com 422 card_token_required.
Repetir o checkout enquanto o primeiro roda. Em lojas com regras de pedido, uma segunda chamada simultânea responde 409 checkout_in_progress; espere em vez de repetir.

Próximos passos

Ler e adicionar à sacola

Sacola, itens e combos.

Frete e totais

Cotar entrega e conferir o total.

Fechar o pedido

Criar o pedido e pagar.

Pedidos

Acompanhar, cancelar e pedir de novo.

Sacola e checkout da mini-loja

Como a sacola e o checkout da mini-loja do WhatsApp funcionam, em que ordem chamar as rotas e o mapa de todas elas.

Pontos-chave

O servidor é a fonte do valor. O frete, o desconto de Pix, os impostos e o total são sempre recalculados no servidor. O que o navegador manda (shipping_choice, expected_total_cents) é conferido, nunca usado como preço.
Total que mudou é erro, não surpresa. Se você manda expected_total_cents no checkout e o total real for outro, a resposta é 409 checkout_total_changed com os totais novos. Mostre ao cliente e peça nova confirmação.
Pagar só parte da sacola. shipping, totals, validate e checkout aceitam line_ids, os itens marcados. Só eles são cotados, validados e pedidos; o resto fica na sacola.
O cartão online é cobrado antes do pedido existir. Se o cartão for recusado, nenhum pedido é criado e a sacola continua intacta.
Dinheiro em centavos, ids UUID. Os textos message já vêm em português para o cliente.
Cada rota exige o token da mini-loja no caminho. Visitante precisa que a loja permita comprar sem conta (allow_guest_checkout); senão responde 403 account_required.

Como funciona

Adicionar itens→Endereço→Frete→Totais e validação→Pagamento→Pedido

Montar a sacola
POST /cart/{token}/items adiciona produtos (veja Variação e frete para produtos com escolha); PATCH altera quantidades. A resposta é sempre a sacola inteira já recalculada.
Descontos
Cupom e cashback reduzem o total. Promoções automáticas da loja já aparecem na sacola (cart_promotions).
Endereço e frete
O cliente informa ou escolhe um endereço salvo. Com o CEP, POST /cart/{token}/shipping lista as opções de entrega.
Totais e validação
POST /cart/{token}/totals mostra o total exato com frete, impostos e desconto da forma de pagamento. POST /cart/{token}/validate confere exigências (idade, CNPJ).
Fechar o pedido
POST /cart/{token}/checkout cria o pedido e devolve como pagar (Pix, boleto, cartão). Depois, acompanhe em Pedidos.

Conceitos-chave

A sacola e suas linhas

Marca na linha	Significa
`unavailable: true`	O produto deixou de ser vendido. A linha continua visível para o cliente poder removê-la, mas não pode ser pedida.
`stock_status`	`ok`, `limited` (estoque menor que a quantidade) ou `out`. Com `limited` e `out`, `available_qty` diz quanto dá.
`is_gift: true`	Brinde que a sacola concedeu. Acompanha os itens que dão direito a ele e não é marcado sozinho.
`bundle_id`	A linha veio de um combo "compre junto" e divide o desconto do combo. Combo é vendido inteiro ou nenhum.
`pending_choices`	Falta uma opção obrigatória (item entrou pelos favoritos). O checkout recusa até resolver.

Método	Rota	O que faz	Página
GET	`/api/v1/storefront/wa-coex/cart/{token}`	Lê a sacola	Ler e adicionar à sacola
POST	`/api/v1/storefront/wa-coex/cart/{token}/items`	Adiciona um produto	Ler e adicionar à sacola
POST	`/api/v1/storefront/wa-coex/cart/{token}/combo`	Adiciona um combo	Ler e adicionar à sacola
PATCH	`/api/v1/storefront/wa-coex/cart/{token}/items/{itemID}`	Altera a quantidade	Alterar itens
PUT	`/api/v1/storefront/wa-coex/cart/{token}/items/{itemID}/configuration`	Troca variação, opções e quantidade	Alterar itens
DELETE	`/api/v1/storefront/wa-coex/cart/{token}/items/{itemID}`	Remove a linha	Alterar itens
POST	`/api/v1/storefront/wa-coex/cart/{token}/coupon`	Aplica um cupom	Cupom e cashback
DELETE	`/api/v1/storefront/wa-coex/cart/{token}/coupon`	Remove o cupom	Cupom e cashback
GET	`/api/v1/storefront/wa-coex/cashback/{token}`	Saldo e uso do cashback	Cupom e cashback
POST	`/api/v1/storefront/wa-coex/cashback/{token}`	Usa o cashback	Cupom e cashback
DELETE	`/api/v1/storefront/wa-coex/cashback/{token}`	Deixa de usar o cashback	Cupom e cashback
GET	`/api/v1/storefront/wa-coex/addresses/{token}`	Lista os endereços salvos	Endereços
POST	`/api/v1/storefront/wa-coex/addresses/{token}`	Salva um endereço	Endereços
DELETE	`/api/v1/storefront/wa-coex/addresses/{token}/{addressID}`	Apaga um endereço	Endereços
POST	`/api/v1/storefront/wa-coex/cart/{token}/shipping`	Cota o frete para um CEP	Frete e totais
POST	`/api/v1/storefront/wa-coex/cart/{token}/totals`	Calcula o total exato	Frete e totais
POST	`/api/v1/storefront/wa-coex/cart/{token}/validate`	Confere exigências do pedido	Frete e totais
GET	`/api/v1/storefront/wa-coex/cart/{token}/sales-reps`	Consultores para escolher	Frete e totais
GET	`/api/v1/storefront/wa-coex/payments/{token}/eligible`	Formas de pagamento disponíveis	Frete e totais
POST	`/api/v1/storefront/wa-coex/cart/{token}/checkout`	Cria o pedido	Fechar o pedido
GET	`/api/v1/storefront/wa-coex/cart/{token}/card-tokenization`	Chave pública para tokenizar o cartão	Pagar com cartão
GET	`/api/v1/storefront/wa-coex/pay/{token}/card-options`	Parcelas do cartão de um pedido	Pagar com cartão
POST	`/api/v1/storefront/wa-coex/pay/{token}/card`	Cobra o cartão de um pedido existente	Pagar com cartão
GET	`/api/v1/storefront/wa-coex/pay/{token}/status/{orderID}`	Consulta se o pagamento do pedido caiu	Pagamento do pedido
GET	`/api/v1/storefront/wa-coex/pay/{token}/cards`	Lista os cartões salvos	Cartões salvos
DELETE	`/api/v1/storefront/wa-coex/pay/{token}/cards/{cardID}`	Apaga um cartão salvo	Cartões salvos

Erros comuns

Alterar pelo product_id. Alterar e remover usam o item_id da linha. O product_id só funciona quando o produto aparece em uma linha única.
Calcular o total no cliente. Some total_cents - cart_promotion_discount_cents - discount_cents só para exibir. Para cobrar, use /totals; o checkout recalcula de qualquer jeito.
Mandar um shipping_choice antigo. Se o CEP ou a sacola mudou, a escolha deixa de existir na cotação e o checkout responde 409 invalid_shipping_choice. Recote e peça nova escolha.
Esquecer o documento. cpf é obrigatório e validado, mesmo para cliente que já tem conta.
Enviar o número do cartão para a Pagar.me. Quando o gateway é a Pagar.me, o cartão novo precisa ser tokenizado no navegador (card_token); número e CVV no corpo são recusados com 422 card_token_required.
Repetir o checkout enquanto o primeiro roda. Em lojas com regras de pedido, uma segunda chamada simultânea responde 409 checkout_in_progress; espere em vez de repetir.

Próximos passos

Ler e adicionar à sacola

Sacola, itens e combos.

Frete e totais

Cotar entrega e conferir o total.

Fechar o pedido

Criar o pedido e pagar.

Pedidos

Acompanhar, cancelar e pedir de novo.