Conceder e consumir créditos

Gerencie o ciclo completo de créditos: conceda saldo, acompanhe o consumo e configure expirações.

Conceder créditos

No Dashboard, acesse o cliente e adicione créditos ao seu pool:

Valor: Montante em reais a ser creditado
Fonte: Motivo da concessão (compra, bônus, reembolso)
Expiração: Data limite para uso dos créditos (opcional)

Créditos com expiração são consumidos antes de créditos sem expiração (FIFO por data de validade).

Consumo automático

Quando uma fatura é gerada, a Aira verifica se o cliente possui saldo de créditos disponível:

Se sim — o saldo é aplicado, reduzindo o valor a pagar na fatura
Se o saldo cobre parcialmente — a diferença é cobrada normalmente
Se o saldo cobre totalmente — a fatura é emitida com valor zero

Histórico de transações

Cada movimentação de créditos é registrada com:

Tipo (concessão, consumo, expiração, reembolso)
Valor
Data
Referência (fatura ou pool associado)

Isso garante rastreabilidade completa para fins de auditoria e reconciliação.

Gerenciar credit pools via API

O pool de créditos de um cliente pode ser criado e mantido pela API, autenticada por chave de API (header X-API-KEY).

Método	Endpoint	Ação
`POST`	`/v1/credit-pools/`	Criar um credit pool
`PUT`	`/v1/credit-pools/{id}`	Atualizar um credit pool
`GET`	`/v1/credit-pools/by-customer`	Listar os pools de um cliente

Campos do credit pool

Campo	Obrigatório	Descrição
`customerId`	sim	UUID do cliente dono do pool
`currencyUnitCode`	sim	Código da unidade de moeda dos créditos — use uma unidade não-padrão cadastrada no tenant (ex: `USD`)
`startDate`	sim	Data (`YYYY-MM-DD`) em que os créditos iniciais são carregados
`renewalCreditAmount`	sim	Créditos concedidos a cada renovação (string decimal)
`topUpSettings`	sim	Configuração de compra de pacotes de créditos (abaixo)

topUpSettings define como o cliente compra créditos adicionais:

Campo	Descrição
`creditPackageAmount`	Créditos por pacote comprado (string decimal)
`price`	Preço por pacote, em centavos (número inteiro ≥ 1)

As compras de pacote aparecem na fatura do cliente como itens de compra de crédito. Na atualização (PUT), envie renewalCreditAmount e topUpSettings — ambos obrigatórios. A resposta inclui também createdBy, o UUID de quem configurou o pool.

Exemplo: criar um pool em USD

curl -X POST https://api.useaira.com/v1/credit-pools/ \
  -H "X-API-KEY: sua_chave_api" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "c0a80121-0000-0000-0000-000000000000",
    "currencyUnitCode": "USD",
    "startDate": "2026-08-01",
    "renewalCreditAmount": "1000",
    "topUpSettings": {
      "creditPackageAmount": "500",
      "price": 250000
    }
  }'

A moeda do pool é sempre uma unidade de moeda de créditos própria, diferente da moeda padrão do tenant. Cadastre a unidade (ex: USD) antes de criar o pool. É essa unidade que as cobranças de uso que consomem créditos referenciam via currencyUnitCode.

Próximos passos

Visão geral de créditos — entenda como o sistema de créditos funciona
Faturas — veja o impacto dos créditos nas faturas

​Conceder créditos

​Consumo automático

​Histórico de transações

​Gerenciar credit pools via API

​Campos do credit pool

​Exemplo: criar um pool em USD

​Próximos passos

Conceder créditos

Consumo automático

Histórico de transações

Gerenciar credit pools via API

Campos do credit pool

Exemplo: criar um pool em USD

Próximos passos