Reportar saldos

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 a cada ciclo.

Enviar as leituras

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

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`	Um item por unidade contada, cada um com um `id` e, opcionalmente, um `name`. O tamanho do array deve ser exatamente igual ao `total`

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.

O payload existe para auditoria: sem ele, uma fatura afirmaria “47 usuários” sem que ninguém pudesse conferir quais 47. 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

Lote atômico

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

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.

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 o dia marcado como Corrigido
Um occurredAt novo é uma leitura independente, com seu próprio histórico de versões

Aira — Histórico de saldos de um cliente, com um dia marcado como Corrigido

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 e o payload corretos.
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 — o que são licenças e como criar o catálogo
Planos — monte o plano que vai precificar a licença

​Enviar as leituras

​Lote atômico

​Correções e versionamento

​Boas práticas

​Próximos passos

Enviar as leituras

Lote atômico

Correções e versionamento

Boas práticas

Próximos passos