> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bukiopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Validar Cupom de Desconto

> Endpoint público que valida um código de cupom e devolve o desconto em reais calculado sobre o total do pedido.

Use este endpoint público para validar um código de cupom durante o checkout. Ele verifica se o cupom está ativo, dentro do limite de usos e dentro da validade, e devolve o valor do desconto calculado sobre o total informado. Por ser público, pode ser chamado direto do frontend sem expor sua API Key.

## Método

`POST /api/v1/coupons/validate`

<Note>
  Este endpoint é **público** e não requer o header `Authorization`. Pode ser chamado direto do frontend da sua loja, sem expor sua API Key ao cliente.
</Note>

## Parâmetros do corpo

<ParamField body="code" type="string" required>
  Código do cupom a ser validado, por exemplo `DESCONTO10`.
</ParamField>

<ParamField body="store_id" type="string" required>
  UUID da loja à qual o cupom pertence.
</ParamField>

<ParamField body="total" type="number" required>
  Valor total do pedido **em reais**, com decimais, sobre o qual o desconto será calculado. Exemplo: `100` para R\$ 100,00.
</ParamField>

<ParamField body="product_ids" type="array">
  UUIDs dos produtos do carrinho. Obrigatório quando o cupom vale só para produtos ou categorias específicas.
</ParamField>

## Exemplo de requisição

```bash theme={null}
curl -X POST 'https://api.bukiopay.com/api/v1/coupons/validate' \
  --header 'Content-Type: application/json' \
  --data '{
    "code": "DESCONTO10",
    "store_id": "550e8400-e29b-41d4-a716-446655440000",
    "total": 100
  }'
```

## Resposta com cupom válido

```json theme={null}
{
  "valid": true,
  "coupon": {
    "id": "8f14e45f-ea2f-4a9d-bc52-3d19c9ea6d42",
    "code": "DESCONTO10",
    "type": "percentage",
    "value": 10,
    "discount": 10,
    "finalTotal": 90
  }
}
```

## Cupom recusado

Quando o cupom não pode ser aplicado, a API responde `400` com um `message` explicando o motivo — cupom inexistente, expirado, inativo, limite de usos atingido, valor mínimo de compra não alcançado ou produto fora da lista de aplicação.

## Campos da resposta

<ResponseField name="valid" type="boolean">
  `true` quando o cupom pode ser aplicado ao pedido.
</ResponseField>

<ResponseField name="coupon" type="object">
  Detalhes do cupom e o desconto já calculado.

  <Expandable title="Propriedades do cupom">
    <ResponseField name="id" type="string">
      UUID do cupom.
    </ResponseField>

    <ResponseField name="code" type="string">
      Código do cupom validado.
    </ResponseField>

    <ResponseField name="type" type="string">
      `percentage` para desconto proporcional ou `fixed` para valor fixo.
    </ResponseField>

    <ResponseField name="value" type="number">
      Valor configurado no cupom. Em `percentage` é a porcentagem; em `fixed` é o valor em reais.
    </ResponseField>

    <ResponseField name="discount" type="number">
      Desconto **em reais** calculado sobre o `total` enviado. Exemplo: um pedido de \$100 com cupom de 10% devolve `10`. Cupons percentuais respeitam o teto de desconto configurado, e cupons de valor fixo nunca passam do total do pedido.
    </ResponseField>

    <ResponseField name="finalTotal" type="number">
      Total do pedido já com o desconto aplicado, em reais.
    </ResponseField>
  </Expandable>
</ResponseField>

<Tip>
  Use sempre o `discount` devolvido pela API para aplicar o desconto. Calcular no frontend abre espaço para o cliente manipular o valor, e a API é quem garante que o cupom ainda é válido no momento da compra.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.