Dois conceitos garantem a qualidade dos dados de uso na Aira: propriedades permitem segmentação granular, e idempotência garante que nenhum evento seja contado duas vezes.
Propriedades de eventos
Além dos campos obrigatórios, cada evento pode conter propriedades adicionais dentro do objetoproperties. Essas propriedades servem para dois fins:
- Filtragem em recursos — crie recursos que contam apenas eventos com determinadas propriedades
- Rastreabilidade — registre contexto adicional que ajuda na análise e auditoria
O campo value
O campo value dentro de properties é obrigatório em todo evento. Ele representa a quantidade consumida naquela ação:
Para recursos monetários, envie o valor em centavos. Por exemplo,
R$ 1.200,50 deve ser enviado como 120050. Isso evita problemas de arredondamento com números decimais.Idempotência
A chave de idempotência (idempotencyKey) é um identificador único para cada evento. Se você enviar o mesmo evento duas vezes com a mesma chave, a Aira grava apenas a primeira ocorrência — o reenvio é rejeitado com o código duplicated_idempotency_key e, como o envio é atômico, nenhum evento daquele lote é gravado.
Por que isso importa
Em sistemas distribuídos, falhas de rede e retentativas são comuns. Sem idempotência, uma retentativa após timeout poderia duplicar um evento, resultando em cobrança dobrada. A chave de idempotência elimina esse risco: se a retentativa devolverduplicated_idempotency_key, o evento original já está gravado e nada é contado duas vezes — basta remover os eventos já gravados do lote e reenviar os demais.
A unicidade da chave é por tenant — cada workspace tem seu próprio espaço de chaves. Não há conflito entre tenants diferentes.
Como gerar boas chaves
A forma recomendada é gerar um UUID para cada evento. Isso garante que cada evento tenha um identificador único e irrepetível.Próximos passos
- Enviar eventos — veja os diferentes métodos de envio
- Recursos — entenda como eventos são filtrados e agregados para cobrança