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

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.

Em cobranças pró-rata, 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

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:

{
  "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.

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.

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

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 — 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

​Enviar só a quantidade

​Lote atômico

​Correções e versionamento

​Boas práticas

​Próximos passos

Enviar as leituras

Enviar só a quantidade

Lote atômico

Correções e versionamento

Boas práticas

Próximos passos