API atual/Referência completa/Mini-loja WhatsApp: sacola e checkout

Cupom e cashback

Aplica ou remove um cupom de desconto da sacola e consulta, usa ou devolve o saldo de cashback do cliente.

Os dois descontos manuais da mini-loja são o cupom (um código que o cliente digita) e o cashback (saldo em reais que o cliente acumulou em compras anteriores e pode gastar). Os dois ficam gravados na sacola do token e entram no cálculo de /totals e do checkout.

Promoções automáticas da loja (por quantidade, valor da sacola, grupo de cliente) não passam por aqui: já aparecem na sacola em cart_promotions.

Aplicar um cupom

POST/api/v1/storefront/wa-coex/cart/{token}/couponPública

Valida e aplica um cupom à sacola

O servidor procura o código entre os cupons da mini-loja e, se não achar, no motor de promoções da loja (o mesmo que o checkout usa). Aplicar um cupom novo substitui o anterior. Um cupom de frete grátis não desconta o subtotal: zera o frete nas cotações e no checkout.

Na loja que esconde preço até o login, a rota responde 403 account_required. Se a loja desligou cupons, responde 403 feature_not_available.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

codestringobrigatório

Código do cupom. Espaços nas pontas são removidos e a letra é convertida para maiúscula.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/cart/$TOKEN/coupon" \
  -H "Content-Type: application/json" \
  -d '{"code":"BEMVINDO10"}'

Resposta

200Cupom aplicado

json

{
  "valid": true,
  "code": "BEMVINDO10",
  "discount_cents": 1840,
  "free_shipping": false,
  "message": "Cupom aplicado",
  "percent": 10
}

200Cupom recusado

json

{
  "valid": false,
  "discount_cents": 0,
  "free_shipping": false,
  "message": "cupom não encontrado ou inativo"
}

Campos da resposta

validboolean

true quando o cupom foi aplicado.

codestring

Código aplicado, em maiúsculas. Ausente quando recusado.

discount_centsinteger

Desconto em centavos, calculado sobre o subtotal atual da sacola. Nunca maior que o subtotal.

free_shippingboolean

true quando o cupom concede frete grátis.

messagestring

Frase para mostrar ao cliente. Em português, vinda do servidor.

percentinteger

Percentual do desconto, só para cupom percentual da mini-loja. Omitido nos outros.

As mensagens de recusa que o servidor devolve em português incluem Informe um cupom, Cupom inválido, Cupom inativo, Cupom ainda não válido, Cupom expirado, Cupom esgotado e Pedido mínimo de R$ 100,00. Cupons do motor de promoções trazem o motivo próprio dele (por exemplo, o que falta para atingir o mínimo).

Erros

Status	Quando	Corpo
403	A loja esconde preços até o login e o cliente não entrou.	`{"error":"account_required"}`
403	A loja desligou os cupons.	`{"error":"feature_not_available","feature":"coupons","detail":"switched off for this store"}`

Remover o cupom

DELETE/api/v1/storefront/wa-coex/cart/{token}/couponPública

Tira o cupom da sacola

Apaga o cupom gravado na sacola. Chamar sem cupom aplicado também responde 200.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Resposta

200Cupom removido

json

{ "ok": true }

Os erros são os mesmos de Aplicar um cupom: 403 account_required e 403 feature_not_available.

Ver o saldo de cashback

GET/api/v1/storefront/wa-coex/cashback/{token}Pública

Saldo de cashback e quanto dele a sacola atual pode usar

Cashback é crédito em reais que a loja devolve ao cliente depois de compras e que ele pode gastar numa compra futura. O saldo é do telefone do token. Quanto dele pode ser usado depende das regras da loja: pedido mínimo e percentual máximo do valor da sacola (já abatido o cupom).

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wa-coex/cashback/$TOKEN"

Resposta

200Cashback desligado ou sem saldo

json

{ "applied_cents": 0, "balance_cents": 0, "enabled": false, "max_usable_cents": 0 }

200Cliente com saldo

json

{ "applied_cents": 0, "balance_cents": 2500, "enabled": true, "max_usable_cents": 1800 }

Campos da resposta

enabledboolean

A loja tem cashback ligado.

balance_centsinteger

Saldo do cliente, em centavos.

max_usable_centsinteger

Quanto desse saldo a sacola de agora aceita gastar, em centavos. 0 quando o pedido mínimo não foi atingido ou não há saldo.

applied_centsinteger

Quanto já está aplicado na sacola, em centavos.

price_redactedboolean

Só aparece (true) quando a loja esconde preços até o login e o cliente não entrou; os valores vêm zerados.

Usar o cashback

POST/api/v1/storefront/wa-coex/cashback/{token}Pública

Aplica cashback à sacola

Grava na sacola quanto cashback será abatido. O valor aplicado nunca passa de max_usable_cents. Reenviar muda o valor.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

applybooleanpadrão: false

true aplica o máximo permitido.

centsinteger

Valor a aplicar, em centavos. Vale o menor entre cents e o máximo permitido. Se apply é false e cents é 0 ou ausente, o cashback aplicado volta a 0.

Resposta

200Cashback aplicado

json

{
  "ok": true,
  "balance_cents": 2500,
  "applied_cents": 1800,
  "max_usable_cents": 1800,
  "enabled": true
}

200Cashback indisponível neste pedido

json

{
  "ok": false,
  "message": "Cashback indisponível neste pedido",
  "balance_cents": 0,
  "applied_cents": 0,
  "max_usable_cents": 0,
  "enabled": false
}

Os campos têm o mesmo significado de Ver o saldo. Sem saldo, com cashback desligado ou abaixo do pedido mínimo, a resposta é 200 com ok: false.

Erros

Status	Quando	Corpo
403	A loja esconde preços até o login e o cliente não entrou.	`{"error":"account_required"}`

Deixar de usar o cashback

DELETE/api/v1/storefront/wa-coex/cashback/{token}Pública

Zera o cashback aplicado à sacola

Volta o cashback aplicado a 0. O saldo do cliente não muda: ele só deixa de ser abatido nesta sacola.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Resposta

200Cashback removido

json

{ "ok": true, "applied_cents": 0 }

Erro: 403 account_required (mesmas condições acima).

Veja também

API atual/Referência completa/Mini-loja WhatsApp: sacola e checkout

Cupom e cashback

Aplica ou remove um cupom de desconto da sacola e consulta, usa ou devolve o saldo de cashback do cliente.

Promoções automáticas da loja (por quantidade, valor da sacola, grupo de cliente) não passam por aqui: já aparecem na sacola em cart_promotions.

Aplicar um cupom

POST/api/v1/storefront/wa-coex/cart/{token}/couponPública

Valida e aplica um cupom à sacola

Na loja que esconde preço até o login, a rota responde 403 account_required. Se a loja desligou cupons, responde 403 feature_not_available.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

codestringobrigatório

Código do cupom. Espaços nas pontas são removidos e a letra é convertida para maiúscula.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/cart/$TOKEN/coupon" \
  -H "Content-Type: application/json" \
  -d '{"code":"BEMVINDO10"}'

Resposta

200Cupom aplicado

json

{
  "valid": true,
  "code": "BEMVINDO10",
  "discount_cents": 1840,
  "free_shipping": false,
  "message": "Cupom aplicado",
  "percent": 10
}

200Cupom recusado

json

{
  "valid": false,
  "discount_cents": 0,
  "free_shipping": false,
  "message": "cupom não encontrado ou inativo"
}

Campos da resposta

validboolean

true quando o cupom foi aplicado.

codestring

Código aplicado, em maiúsculas. Ausente quando recusado.

discount_centsinteger

Desconto em centavos, calculado sobre o subtotal atual da sacola. Nunca maior que o subtotal.

free_shippingboolean

true quando o cupom concede frete grátis.

messagestring

Frase para mostrar ao cliente. Em português, vinda do servidor.

percentinteger

Percentual do desconto, só para cupom percentual da mini-loja. Omitido nos outros.

Erros

Status	Quando	Corpo
403	A loja esconde preços até o login e o cliente não entrou.	`{"error":"account_required"}`
403	A loja desligou os cupons.	`{"error":"feature_not_available","feature":"coupons","detail":"switched off for this store"}`

Remover o cupom

DELETE/api/v1/storefront/wa-coex/cart/{token}/couponPública

Tira o cupom da sacola

Apaga o cupom gravado na sacola. Chamar sem cupom aplicado também responde 200.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Resposta

200Cupom removido

json

{ "ok": true }

Os erros são os mesmos de Aplicar um cupom: 403 account_required e 403 feature_not_available.

Ver o saldo de cashback

GET/api/v1/storefront/wa-coex/cashback/{token}Pública

Saldo de cashback e quanto dele a sacola atual pode usar

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wa-coex/cashback/$TOKEN"

Resposta

200Cashback desligado ou sem saldo

json

{ "applied_cents": 0, "balance_cents": 0, "enabled": false, "max_usable_cents": 0 }

200Cliente com saldo

json

{ "applied_cents": 0, "balance_cents": 2500, "enabled": true, "max_usable_cents": 1800 }

Campos da resposta

enabledboolean

A loja tem cashback ligado.

balance_centsinteger

Saldo do cliente, em centavos.

max_usable_centsinteger

Quanto desse saldo a sacola de agora aceita gastar, em centavos. 0 quando o pedido mínimo não foi atingido ou não há saldo.

applied_centsinteger

Quanto já está aplicado na sacola, em centavos.

price_redactedboolean

Só aparece (true) quando a loja esconde preços até o login e o cliente não entrou; os valores vêm zerados.

Usar o cashback

POST/api/v1/storefront/wa-coex/cashback/{token}Pública

Aplica cashback à sacola

Grava na sacola quanto cashback será abatido. O valor aplicado nunca passa de max_usable_cents. Reenviar muda o valor.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

applybooleanpadrão: false

true aplica o máximo permitido.

centsinteger

Valor a aplicar, em centavos. Vale o menor entre cents e o máximo permitido. Se apply é false e cents é 0 ou ausente, o cashback aplicado volta a 0.

Resposta

200Cashback aplicado

json

{
  "ok": true,
  "balance_cents": 2500,
  "applied_cents": 1800,
  "max_usable_cents": 1800,
  "enabled": true
}

200Cashback indisponível neste pedido

json

{
  "ok": false,
  "message": "Cashback indisponível neste pedido",
  "balance_cents": 0,
  "applied_cents": 0,
  "max_usable_cents": 0,
  "enabled": false
}

Os campos têm o mesmo significado de Ver o saldo. Sem saldo, com cashback desligado ou abaixo do pedido mínimo, a resposta é 200 com ok: false.

Erros

Status	Quando	Corpo
403	A loja esconde preços até o login e o cliente não entrou.	`{"error":"account_required"}`

Deixar de usar o cashback

DELETE/api/v1/storefront/wa-coex/cashback/{token}Pública

Zera o cashback aplicado à sacola

Volta o cashback aplicado a 0. O saldo do cliente não muda: ele só deixa de ser abatido nesta sacola.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Resposta

200Cashback removido

json

{ "ok": true, "applied_cents": 0 }

Erro: 403 account_required (mesmas condições acima).