Descontos e alocações

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

Tipo de desconto

Monetário
Percentual

Um valor fixo abatido do total.Exemplo: desconto de R$ 500 em uma fatura de R$ 3.000 → total final R$ 2.500.

Uma porcentagem abatida do total.Exemplo: desconto de 10% em uma fatura de R$ 3.000 → total final R$ 2.700.

Onde o desconto incide

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

Manual ou automático

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

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.

Desconto não é crédito. Desconto reduz o valor de uma fatura específica. Crédito é um saldo pré-pago, em moeda alternativa, que abate o uso antes de ele virar fatura. São mecanismos separados.

Gerenciar descontos via API

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 (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`

Campos do desconto

Campo	Valores	Descrição
`target`	`invoice`, `line_item_group`, `line_item`	Onde o desconto incide (ver Onde o desconto 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

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"
  }'

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

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.

Alocações

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

Alocação única
Split percentual

O padrão — toda a fatura é direcionada a um único destinatário. É o comportamento padrão quando nenhuma configuração de alocação é feita.

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%)

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.

Próximos passos

Descontos recorrentes — descontos que se repetem a cada ciclo do contrato
Faturamento de clientes — como faturas são geradas
Documentos fiscais — NFSe, PDF e XML

​Descontos

​Tipo de desconto

​Onde o desconto incide

​Manual ou automático

​Gerenciar descontos via API

​Campos do desconto

​Exemplo: desconto de R$ 50 na fatura inteira

​Alocações

​Próximos passos

Descontos

Tipo de desconto

Onde o desconto incide

Manual ou automático

Gerenciar descontos via API

Campos do desconto

Exemplo: desconto de R$ 50 na fatura inteira

Alocações

Próximos passos