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

> ## Agent Instructions
> Documentação das APIs da DeliveryVip, em português. Regras que mais quebram integrações: (1) Merchant API: faça polling em GET /merchant/v3/events:polling no máximo a cada 30 s por token; confirme todo evento recebido com POST /merchant/v3/events/acknowledgment e corpo [{"id": "<eventId>"}] (o campo lido é id, não eventId), inclusive eventos repetidos ou que o sistema não trata; deduplique por eventId; o evento é só um aviso, busque o pedido na orderURL. (2) Tokens client_credentials valem 24 h e não têm refresh_token: peça outro ao receber 401. (3) Webhooks: valide a assinatura HMAC sobre o corpo bruto e responda 2xx rápido; o polling é a reconciliação. (4) Open Delivery: host od.deliveryvip.com.br, um client_secret por loja, datas em UTC. (5) Fidelidade: o operador implementa 5 rotas assinadas com HMAC e chama o config push; o estorno precisa ser idempotente. (6) Partner API: scope dv.partner. Não invente endpoints: use a referência gerada das specs OpenAPI.

# Adicionar um desconto

> Cadastre um desconto automático ou um cupom, com valor, período e regras de uso.

Cadastra um desconto na loja. O desconto passa a valer em `startsAt` e vale só no canal de venda da própria loja.

## Requisição

**merchantId** `uuid` *required*

A loja.

**type** `string` *required*

`SMART` (automático) ou `COUPON` (cupom). Veja [tipos de desconto](/docs/guides/merchant/discount.md#tipos-de-desconto).

**name** `string`

Nome do desconto. **Obrigatório quando `type` é `SMART`.**

**code** `string`

Código que o cliente digita. **Obrigatório quando `type` é `COUPON`.** Só letras e números, sem espaços, e único entre os cupons não removidos da loja, sem diferenciar maiúsculas de minúsculas.

**startsAt** `datetime` *required*

A partir de quando o desconto vale. Uma data no futuro deixa o desconto `SCHEDULED`.

**endsAt** `datetime`

Até quando o desconto vale. Precisa ser depois de `startsAt`. Sem ele, o desconto não expira.

**rules** `object` *required*

Regras de valor e de uso.

**propriedades**

**value** `number` *required*

Valor do desconto, maior que zero. Em `PERCENTAGE`, no máximo `100`.

**valueType** `string` (default: PERCENTAGE)

`PERCENTAGE` (porcentagem) ou `FIXED_AMOUNT` (valor em reais).

**discountType** `string` (default: TOTAL)

Sobre o que o desconto incide: `SUBTOTAL` (soma dos produtos), `TOTAL` (produtos mais entrega) ou `DELIVERY` (só a entrega).

**minimumOrderValue** `number` (default: 0)

Valor mínimo dos produtos na sacola para o desconto valer. `0` não exige mínimo.

**usageLimit** `integer` (default: 0)

Quantas vezes o desconto pode ser usado no total, somando todos os clientes. `0` é ilimitado.

**usagePerCustomer** `string` (default: ONCE)

`MANY` (qualquer cliente, quantas vezes quiser), `ONCE` (uma vez por cliente) ou `FIRST_ORDER` (só no primeiro pedido do cliente na loja).

**options** `string[]`

Opções extras:

* `NON_PROMOTION_PRODUCTS`: o desconto só incide sobre produtos que não estão em promoção, e o mínimo do pedido considera só esses produtos.
* `CUMULATIVE_WITH_SMART`: o cupom se soma ao desconto automático em vez de substituí-lo. **Só para `COUPON`**: em `SMART`, a API responde `422`.

> [!NOTE]
>
> `status` não é aceito e é ignorado se enviado: ele é calculado a partir das datas. Veja [status](/docs/guides/merchant/discount.md#status).

```bash cURL theme={null}
curl --request POST 'https://api.deliveryvip.com.br/merchant/v3/{merchantId}/discounts' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "COUPON",
    "code": "BEMVINDO10",
    "startsAt": "2024-05-01T00:00:00-03:00",
    "endsAt": "2024-05-31T23:59:59-03:00",
    "rules": {
      "valueType": "PERCENTAGE",
      "value": 10,
      "minimumOrderValue": 50,
      "usageLimit": 100,
      "usagePerCustomer": "FIRST_ORDER",
      "discountType": "SUBTOTAL"
    },
    "options": ["CUMULATIVE_WITH_SMART"]
  }'
```

```js Node.js theme={null}
const response = await fetch(`https://api.deliveryvip.com.br/merchant/v3/${merchantId}/discounts`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'COUPON',
    code: 'BEMVINDO10',
    startsAt: '2024-05-01T00:00:00-03:00',
    endsAt: '2024-05-31T23:59:59-03:00',
    rules: {
      valueType: 'PERCENTAGE',
      value: 10,
      minimumOrderValue: 50,
      usageLimit: 100,
      usagePerCustomer: 'FIRST_ORDER',
      discountType: 'SUBTOTAL',
    },
    options: ['CUMULATIVE_WITH_SMART'],
  }),
})
const discount = await response.json()
```

```python Python theme={null}
response = requests.post(
    f"https://api.deliveryvip.com.br/merchant/v3/{merchant_id}/discounts",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "type": "COUPON",
        "code": "BEMVINDO10",
        "startsAt": "2024-05-01T00:00:00-03:00",
        "endsAt": "2024-05-31T23:59:59-03:00",
        "rules": {
            "valueType": "PERCENTAGE",
            "value": 10,
            "minimumOrderValue": 50,
            "usageLimit": 100,
            "usagePerCustomer": "FIRST_ORDER",
            "discountType": "SUBTOTAL",
        },
        "options": ["CUMULATIVE_WITH_SMART"],
    },
)
discount = response.json()
```

> [accordion] Exemplo de desconto automático (SMART)
>
> ```json theme={null}
> {
>   "type": "SMART",
>   "name": "10% acima de R$ 32",
>   "startsAt": "2024-04-28T17:18:00-03:00",
>   "rules": {
>     "valueType": "PERCENTAGE",
>     "value": 10,
>     "minimumOrderValue": 32,
>     "usagePerCustomer": "MANY",
>     "discountType": "SUBTOTAL"
>   },
>   "options": ["NON_PROMOTION_PRODUCTS"]
> }
> ```

## Resposta

Retorna `200 OK` com o [objeto desconto](/docs/guides/merchant/discount/obter-detalhes-do-desconto.md#resposta).

```json 200 OK theme={null}
{
  "id": "4572126a-6161-4b68-af04-3cb2fb4fa7a5",
  "createdAt": "2024-04-20T19:43:15-03:00",
  "startsAt": "2024-05-01T00:00:00-03:00",
  "endsAt": "2024-05-31T23:59:59-03:00",
  "type": "COUPON",
  "code": "BEMVINDO10",
  "status": "SCHEDULED",
  "rules": {
    "valueType": "PERCENTAGE",
    "value": 10.0,
    "minimumOrderValue": 50.0,
    "usageLimit": 100,
    "usagePerCustomer": "FIRST_ORDER",
    "discountType": "SUBTOTAL"
  },
  "options": ["CUMULATIVE_WITH_SMART"]
}
```

## Erros

Em `422`, o `title` traz os campos com problema e as mensagens de validação.

```json 422 Unprocessable Content theme={null}
{
  "status": "422",
  "title": { "code": ["has already been taken"] }
}
```

| Status | Quando |
| - | - |
| `403 Forbidden` | A loja não contratou o módulo de descontos. |
| `404 Not Found` | O `merchantId` não autorizou o seu app. |
| `422 Unprocessable Content` | `type` ausente ou inválido, `name` ou `code` faltando, `code` repetido ou com espaços, `value` zero ou acima de 100% em `PERCENTAGE`, `endsAt` antes de `startsAt`, `CUMULATIVE_WITH_SMART` num `SMART`. |


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