POST

`shop.desconto.validar`

Calcula descontos com os preços atuais do catálogo. Retorna descontos aplicáveis e eventual recusa do código informado.

Grupo: ShopRevisão: 2026-10-02Escopo recomendado: shop.desconto.validar

Exemplos seguros e fictícios. O domínio example.invalid e a credencial demonstrativa abaixo não funcionam. Use o token real somente no servidor da sua integração e nunca o inclua em páginas públicas.

Parâmetros

Parâmetros aceitos por shop.desconto.validar
Campo	Tipo	Obrigatoriedade	Descrição	Exemplo fictício
`codigo`	string	Opcional	Cupom informado. Normaliza para maiúsculas e remove espaços. Sem código, calcula automáticos.	`"DEMO10"`
`itens`	array<object> \| string JSON	Obrigatório	Lista de itens. Aceita array JSON ou string JSON. Preço enviado pelo cliente é ignorado.	`[{"sku":"DEMO-01","qtd":2}]`
`itens[].sku`	string	um dos dois obrigatório	SKU do produto. Em cada item informado, envie sku OU codigo; sku tem precedência quando ambos são preenchidos.	`"DEMO-01"`
`itens[].codigo`	string	um dos dois obrigatório	Alternativa a itens[].sku. Em cada item informado, é necessário identificar o produto por sku OU codigo.	`"DEMO-01"`
`itens[].qtd`	integer	Opcional	Quantidade; quantidade é alias; mínimo efetivo 1.	`2`
`frete_cents`	integer	Opcional	Cotação de frete em centavos, usada somente para estimar o desconto; o valor final deve ser recalculado no fluxo comercial autorizado.	`900`
`cliente`	object	Opcional	CPF/cpf_cnpj ou email para restrições de uso por comprador. Envie objeto JSON, não string.	`{"email":"comprador@example.com"}`

Exemplos fictícios

Os exemplos documentam o formato; eles não executam nenhuma operação.

Requisição

cURL demonstrativo

curl --request POST \
  'https://example.invalid/api/v1/CREDENCIAL_FICTICIA_SEM_VALOR/shop.desconto.validar' \
  --header 'Content-Type: application/json' \
  --data '{"codigo":"DEMO10","itens":[{"sku":"DEMO-01","qtd":2}],"frete_cents":900,"cliente":{"email":"comprador@example.com"}}'

Corpo JSON

{
  "codigo": "DEMO10",
  "itens": [
    {
      "sku": "DEMO-01",
      "qtd": 2
    }
  ],
  "frete_cents": 900,
  "cliente": {
    "email": "comprador@example.com"
  }
}

Resposta HTTP 200

{
  "ok": true,
  "method": "shop.desconto.validar",
  "result": {
    "descontos": [
      {
        "id": "66666666-6666-4666-8666-666666666666",
        "tipo": "pedido",
        "metodo": "codigo",
        "codigo": "DEMO10",
        "nome": "Desconto de demonstração",
        "valor_cents": 500,
        "valor": 5,
        "skus": [],
        "frete_gratis": false,
        "combina": {
          "produto": false,
          "pedido": false,
          "frete": false
        }
      }
    ],
    "valor_cents": 500,
    "frete_gratis": false,
    "frete_desconto_cents": 0,
    "valor": 5,
    "recusa": null
  }
}

Erros

Condições de erro específicas de shop.desconto.validar
HTTP	Código	Condição
403	`TOKEN_NO_COMPANY`	Token sem empresa associada.

Consulte também os erros globais e limites.

Observações

Tipos: produtos, compre_leve, pedido e frete. Esta consulta não registra o uso do cupom.
valor_cents e valor representam desconto nos produtos; frete_desconto_cents é separado. Não some frete grátis ao desconto de produtos duas vezes.
recusa, quando presente, contém codigo, motivo, min_valor_cents, min_itens e texto; é retorno de negócio HTTP 200.
Motivos: nao_encontrado, inativo, ainda_nao_comecou, expirado, esgotado, ja_usado, exige_identificacao, minimo_valor, minimo_itens, sem_itens_no_alvo, combo_nao_atingido, sem_frete, frete_acima_do_teto e tipo_desconhecido.
Item não encontrado ou sem preço positivo é ignorado nesta estimativa; a validação não garante disponibilidade do carrinho.
Pode haver descontos automáticos mesmo quando o cupom explícito é recusado. Um fluxo comercial posterior deve revalidar o resultado.