> ## 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.

# Descontos

> Crie e gerencie descontos automáticos e cupons de uma loja e acompanhe o resultado de cada um.

A API de descontos permite cadastrar, alterar, ativar, desativar e remover os descontos de uma loja, e consultar quanto cada um vendeu.

> [!WARNING]
>
> **API em beta.** Ela ainda pode mudar. Acompanhe o [changelog](/docs/changelog.md) antes de cada atualização da sua integração.

## Tipos de desconto

> [card] SMART
>
> Desconto automático. Entra sozinho na sacola quando o pedido cumpre as regras, sem o cliente fazer nada. Identificado por `name`.

> [card] COUPON
>
> Cupom. O cliente digita o `code` na sacola para aplicar. Bom para campanhas com influenciadores ou para enviar a um cliente específico.

Um pedido recebe no máximo um desconto `SMART` e um cupom. Se o cliente aplicar um cupom, ele substitui o desconto automático, a menos que o cupom tenha a opção `CUMULATIVE_WITH_SMART`: nesse caso os dois se somam.

## Status

O `status` não é um campo que você envia. Ele é calculado a partir de `startsAt` e `endsAt` a cada consulta:

| `status` | Quando |
| - | - |
| `SCHEDULED` | `startsAt` ainda não chegou. |
| `ACTIVE` | Já começou e `endsAt` é vazio ou ainda não passou. |
| `OVERDUE` | `endsAt` já passou. |

![Estados SCHEDULED, ACTIVE e OVERDUE e as transições por data e pelas ações available e unavailable](https://mintcdn.com/deliveryvip-a4256422/ELxpcniK2_BP8zxT/images/desconto-status.png?fit=max\&auto=format\&n=ELxpcniK2_BP8zxT\&q=85\&s=c5e97296731b0e999c263aabc382e08a)

Status de um desconto

Para ligar ou desligar um desconto na hora, use as [ações](/docs/guides/merchant/discount/acoes-dos-descontos.md).

## Endpoints

Todas as rotas ficam em `https://api.deliveryvip.com.br/merchant/v3/{merchantId}/discounts`.

| Ação | Endpoint | Sucesso |
| - | - | - |
| [Listar descontos](/docs/guides/merchant/discount/listar-descontos.md) | `GET /discounts` | `200` ou `204` |
| [Obter um desconto](/docs/guides/merchant/discount/obter-detalhes-do-desconto.md) | `GET /discounts/{discountId}` | `200` |
| [Estatísticas](/docs/guides/merchant/discount/obter-estatistica-do-desconto.md) | `GET /discounts/{discountId}/stats` | `200` |
| [Adicionar](/docs/guides/merchant/discount/adicionar-um-desconto.md) | `POST /discounts` | `200` |
| [Atualizar](/docs/guides/merchant/discount/atualizar-um-desconto.md) | `PATCH /discounts/{discountId}` | `200` |
| [Remover](/docs/guides/merchant/discount/remover-um-desconto.md) | `DELETE /discounts/{discountId}` | `200` |
| [Ativar](/docs/guides/merchant/discount/acoes-dos-descontos/ativar-um-desconto.md) | `POST /discounts/{discountId}/available` | `200` |
| [Desativar](/docs/guides/merchant/discount/acoes-dos-descontos/desativar-um-desconto.md) | `POST /discounts/{discountId}/unavailable` | `200` |

## Requisitos

> [!NOTE]
>
> A loja precisa ter o módulo de descontos contratado. Sem ele, **todas** as rotas respondem `403` com `"title": "growth_discount_not_hired"`.

Os descontos criados ou alterados pela API valem só no canal de venda da própria loja.

## Erros comuns

Os erros seguem o [formato padrão](/docs/inicio/conceitos/erros.md): `{ "status": "...", "title": ... }`.

| Status | Quando |
| - | - |
| `401 Unauthorized` | Token ausente, expirado ou inválido. |
| `403 Forbidden` | A loja não contratou o módulo de descontos (`growth_discount_not_hired`). |
| `404 Not Found` | O `merchantId` não autorizou o seu app, ou o desconto não existe ou foi removido. |
| `422 Unprocessable Content` | Dados inválidos no cadastro ou na atualização. O `title` traz os campos com problema. |


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