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

# Descontos e alocações

> Aplique descontos monetários ou percentuais e distribua o valor da fatura entre múltiplos destinatários.

> Descontos reduzem o valor da fatura. Alocações dividem o valor entre múltiplas entidades. Ambos são configurados por fatura ou por contrato.

## Descontos

Um desconto reduz o valor de uma fatura. Pode ser **pontual** (aplicado a uma fatura específica) ou **recorrente** (definido no contrato e repetido a cada ciclo).

<h3 id="tipo-de-desconto">
  Tipo de desconto
</h3>

<Tabs>
  <Tab title="Monetário">
    Um valor fixo abatido do total.

    **Exemplo:** desconto de `R$ 500` em uma fatura de `R$ 3.000` → total final `R$ 2.500`.
  </Tab>

  <Tab title="Percentual">
    Uma porcentagem abatida do total.

    **Exemplo:** desconto de 10% em uma fatura de `R$ 3.000` → total final `R$ 2.700`.
  </Tab>
</Tabs>

<h3 id="onde-incide">
  Onde o desconto incide
</h3>

Um desconto pode ser direcionado a três níveis de uma fatura:

| Nível           | O que abate                                                                   |
| --------------- | ----------------------------------------------------------------------------- |
| Fatura inteira  | Distribui o desconto sobre todos os itens da fatura                           |
| Grupo de itens  | Abate apenas os itens de um grupo — por exemplo, tudo que pertence a um plano |
| Item específico | Abate um único item de linha                                                  |

<br />

<h3 id="manual-ou-automatico">
  Manual ou automático
</h3>

A origem de um desconto pode ser manual ou gerada pela própria Aira:

| Origem                     | Como surge                                                                                                    |
| -------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Manual**                 | Aplicado pela sua equipe a uma fatura específica                                                              |
| **Recorrente do contrato** | Definido no contrato e materializado a cada ciclo, dentro de uma janela de datas                              |
| **Prorrata**               | Gerado automaticamente quando o contrato inicia ou encerra no meio de um ciclo, abatendo os dias não cobrados |

<Note>
  Um desconto nunca abate mais do que o valor disponível: um desconto de `R$ 1.000` em uma fatura de `R$ 500` reduz apenas `R$ 500`. Quando o valor é distribuído entre vários itens, o arredondamento é tratado para que a soma das partes bata exatamente com o desconto total.
</Note>

<Info>
  **Desconto não é crédito.** Desconto reduz o valor de uma fatura específica. [Crédito](/creditos/visao-geral) é um saldo pré-pago, em moeda alternativa, que abate o uso antes de ele virar fatura. São mecanismos separados.
</Info>

<br />

<h2 id="gerenciar-via-api">
  Gerenciar descontos via API
</h2>

Os descontos **pontuais** de uma fatura podem ser criados, listados, atualizados e removidos pela API. As requisições são autenticadas por [chave de API](/api-reference/autenticacao) (header `X-API-KEY`).

| Método   | Endpoint                                          | Ação                          | Permissão        |
| -------- | ------------------------------------------------- | ----------------------------- | ---------------- |
| `POST`   | `/v1/invoices/{invoiceId}/discounts`              | Criar um desconto             | `invoices:write` |
| `GET`    | `/v1/invoices/{invoiceId}/discounts`              | Listar os descontos da fatura | `invoices:read`  |
| `PUT`    | `/v1/invoices/{invoiceId}/discounts/{discountId}` | Atualizar um desconto         | `invoices:write` |
| `DELETE` | `/v1/invoices/{invoiceId}/discounts/{discountId}` | Remover um desconto           | `invoices:write` |

<h3 id="campos-desconto-fatura">
  Campos do desconto
</h3>

| Campo                  | Valores                                   | Descrição                                                                                                                                                                    |
| ---------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `target`               | `invoice`, `line_item_group`, `line_item` | Onde o desconto incide (ver [Onde o desconto incide](#onde-incide))                                                                                                          |
| `targetIdempotencyKey` | string                                    | Chave do alvo. Para a fatura inteira, use a `idempotencyKey` da fatura; para um grupo ou item, a `idempotencyKey` dele — ambas disponíveis em `GET /v1/invoices/{invoiceId}` |
| `method`               | `fixed`, `percentage`                     | Valor fixo (em centavos) ou percentual (em *basis points*: `10000` = 100%)                                                                                                   |
| `amount`               | número                                    | Centavos quando `fixed`; basis points (0–10000) quando `percentage`                                                                                                          |
| `description`          | string                                    | Texto exibido na fatura                                                                                                                                                      |

### Exemplo: desconto de R\$ 50 na fatura inteira

```bash theme={null}
curl -X POST https://api.useaira.com/v1/invoices/{invoiceId}/discounts \
  -H "X-API-KEY: sua_chave_api" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "invoice",
    "targetIdempotencyKey": "{idempotencyKey-da-fatura}",
    "method": "fixed",
    "amount": 5000,
    "description": "Desconto comercial"
  }'
```

```json theme={null}
{
  "id": "a1b2c3d4-0000-0000-0000-000000000000",
  "target": "invoice",
  "targetIdempotencyKey": "{idempotencyKey-da-fatura}",
  "method": "fixed",
  "amount": 5000,
  "description": "Desconto comercial",
  "reason": "manual_discount",
  "isActive": true
}
```

<Note>
  Descontos criados pela API são sempre da origem `manual_discount` — não é possível criar pela API um desconto de sistema (recorrente do contrato ou prorrata). Ao **atualizar** um desconto, a origem (`reason`) original é preservada.
</Note>

<br />

<h2 id="alocacoes">
  Alocações
</h2>

Alocações definem como o valor da fatura é distribuído entre destinatários:

<Tabs>
  <Tab title="Alocação única">
    O padrão — toda a fatura é direcionada a um único destinatário. É o comportamento padrão quando nenhuma configuração de alocação é feita.
  </Tab>

  <Tab title="Split percentual">
    O valor da fatura é dividido entre múltiplos destinatários por porcentagem.

    **Exemplo:** fatura de `R$ 10.000` dividida 60/40:

    * Destinatário A: `R$ 6.000` (60%)
    * Destinatário B: `R$ 4.000` (40%)

    <Tip>
      Splits percentuais são úteis para cenários de revenue sharing, onde a receita é dividida entre múltiplas entidades legais ou unidades de negócio.
    </Tip>
  </Tab>
</Tabs>

<br />

<h2 id="proximos-passos">
  Próximos passos
</h2>

* [Descontos recorrentes](/contratos/descontos-recorrentes) — descontos que se repetem a cada ciclo do contrato
* [Faturamento de clientes](/faturas/faturamento-de-clientes) — como faturas são geradas
* [Documentos fiscais](/faturas/documentos-fiscais) — NFSe, PDF e XML