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

# Reportar saldos

> Envie as leituras de saldo de licenças para a Aira em lote, com validação atômica e histórico versionado por cliente.

> Sua aplicação informa quantas licenças cada cliente tem naquele momento. Cada leitura declara um estado, não acumula como um evento, e a Aira cobra a última quantidade conhecida no fechamento de cada período da cobrança por licença.

## Enviar as leituras

Sua aplicação envia as leituras em lote, com uma chave de API que tenha a permissão `licenses:write`.

```bash theme={null}
curl -X POST https://api.useaira.com/v1/licenses/report-balances \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: sua_chave_api" \
  -d '{
    "balances": [
      {
        "code": "usuarios_ativos",
        "customerExternalId": "acme_001",
        "occurredAt": "2024-01-15T03:00:00Z",
        "total": 3,
        "payload": [
          { "id": "u_1024", "name": "Ana Souza", "perfil": "admin" },
          { "id": "u_1088", "name": "Bruno Lima", "perfil": "operador" },
          { "id": "u_1153", "name": "Carla Dias", "perfil": "operador" }
        ]
      }
    ]
  }'
```

| Campo | Descrição |
| - | - |
| `code` | Código da licença no catálogo, sensível a maiúsculas e minúsculas |
| `customerExternalId` | ID externo do cliente. Um ID que não existe no cadastro é aceito e gravado, mas nunca entra em nenhuma fatura |
| `occurredAt` | Momento da leitura em ISO 8601 **com fuso explícito**, como `2024-01-15T03:00:00Z`. Não pode estar no futuro |
| `total` | Quantidade reportada. Inteiro maior ou igual a `0` |
| `payload` | Opcional. Um item por unidade contada, cada um com um `id` e, opcionalmente, um `name`. Quando enviado, o tamanho do array deve ser **exatamente igual** ao `total` |

> [!TIP]
>
> Você pode enviar até **10.000 leituras por requisição**, em um corpo de até 16 MiB. Não há limite de requisições por minuto, mas recomendamos distribuir o envio ao longo do tempo para evitar picos.

> [!NOTE]
>
> Em cobranças [pró-rata](https://docs.useaira.com/licencas/cobranca-pro-rata.md), o `occurredAt` define **em que dia** cada mudança de quantidade passa a valer — e, com isso, quantos dias restantes do ciclo cada ajuste cobra. Reporte as leituras com o momento real da mudança, não o momento do envio.

O `payload` existe para auditoria: com ele, quem confere uma fatura de "47 usuários" vê **quais** 47 foram contados. Chaves além de `id` e `name` são preservadas como propriedades da unidade, visíveis junto da leitura.

![Aira — Itens do payload de uma leitura, na aba Atual](https://mintcdn.com/aira-e93056c6/EK-hZ7zZzaymZBxr/static/license-balance-drawer.png?fit=max\&auto=format\&n=EK-hZ7zZzaymZBxr\&q=85\&s=9b39380adf2c2087dad510e3f2d714cf)

### Enviar só a quantidade

Quando listar as unidades não faz sentido, como em uma base de contatos com centenas de milhares de registros, omita o `payload` e envie só o `total`:

```json theme={null}
{
  "balances": [
    {
      "code": "contatos",
      "customerExternalId": "acme_001",
      "occurredAt": "2024-01-15T03:00:00Z",
      "total": 250000
    }
  ]
}
```

A cobrança usa apenas o `total`, então a fatura sai igual com ou sem o `payload`. A leitura só não mostra quais unidades foram contadas.

> [!WARNING]
>
> Um `payload` vazio (`[]`) não equivale a omitir o campo. Com `total` maior que `0`, ele é recusado porque o tamanho do array não bate com o `total`.

## Lote atômico

O envio opera como uma **transação atômica**: se qualquer leitura do lote falhar na validação, nenhuma leitura é registrada.

> [!NOTE]
>
> Se você enviar 500 leituras e 1 tiver o `code` errado, as 499 válidas também são rejeitadas. Valide antes de enviar ou trate o erro e reenvie o lote corrigido. Os códigos de erro estão em [Respostas de erro](https://docs.useaira.com/api-reference/error-responses.md).

## Correções e versionamento

Uma leitura é identificada pela combinação de `code`, `customerExternalId` e `occurredAt`. O histórico é somente-anexação: nada é atualizado nem apagado.

* **Reenvio idêntico** não grava nada, então timeouts e retentativas não criam duplicatas
* **Reenvio com `total` ou `payload` diferente** anexa uma nova versão que passa a valer, e o histórico mostra a versão nova logo acima da leitura que ela corrige
* **Reenvio sem o `payload`** de uma leitura que tinha unidades também anexa uma nova versão, e ela passa a valer sem a lista
* **Um `occurredAt` novo** é uma leitura independente, com seu próprio histórico de versões

![Aira — Histórico de saldos de um cliente, com as leituras informadas e suas versões](https://mintcdn.com/aira-e93056c6/EK-hZ7zZzaymZBxr/static/license-balance-history.png?fit=max\&auto=format\&n=EK-hZ7zZzaymZBxr\&q=85\&s=84f13c10d639daee7af799578e15ae5f)

> [!NOTE]
>
> Uma correção enviada depois que a fatura do ciclo já foi emitida **não altera essa fatura**. Cada cálculo é fixado nas versões que existiam quando ele rodou.

## Boas práticas

* **Reporte uma leitura por cliente por dia:** a quantidade de um dia é definida pela última leitura enviada até o fim daquele dia. Se nenhuma leitura chegar, a última quantidade conhecida é mantida, inclusive por ciclos inteiros.

* **Para corrigir o passado, reenvie o mesmo momento:** repita `code`, `customerExternalId` e `occurredAt` com o `total` correto e, se você envia as unidades, o `payload` correto.

* **Para carregar histórico, envie os momentos passados:** cada `occurredAt` distinto é uma leitura independente, então um único lote pode cobrir meses.

## Próximos passos

* [Licenças](https://docs.useaira.com/licencas/visao-geral.md) — o que são licenças e como criar o catálogo
* [Planos](https://docs.useaira.com/planos/criar-planos.md) — monte o plano que vai precificar a licença


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