Skip to main content
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 objeto properties. Essas propriedades servem para dois fins:
  1. Filtragem em recursos — crie recursos que contam apenas eventos com determinadas propriedades
  2. Rastreabilidade — registre contexto adicional que ajuda na análise e auditoria
{
  "idempotencyKey": "evt-2024-01-15-001",
  "customerExternalId": "acme_001",
  "eventName": "api_request",
  "occurredAt": "2024-01-15T14:30:00Z",
  "properties": {
    "value": 1,
    "endpoint": "/v1/payments",
    "method": "POST",
    "status_code": 200,
    "region": "sa-east-1"
  }
}
No Dashboard, você pode visualizar todas as propriedades de um evento clicando sobre ele na listagem de eventos:
Propriedades de um evento no Dashboard da Aira

​
O campo value

O campo value dentro de properties é obrigatório em todo evento. Ele representa a quantidade consumida naquela ação:
CenárioValor de valueSignificado
Requisição de API1Uma requisição
Armazenamento5050 GB
Transação financeira150000R$ 1.500,00 (em centavos)
Horas de processamento44 horas (inteiro)
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 processa apenas a primeira ocorrência e ignora a duplicata.

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

​
Exclusão de eventos

Eventos são soft-deleted (exclusão lógica) — o registro é marcado como excluído mas não é removido do banco de dados. Isso preserva o histórico para auditoria.
Eventos que já foram usados no cálculo de faturas emitidas (faturas com status Emitida ou posterior) não podem ser excluídos. A Aira retorna um erro indicando quais faturas bloqueiam a exclusão.

​
Próximos passos

  • Enviar eventos — veja os diferentes métodos de envio
  • Recursos — entenda como eventos são filtrados e agregados para cobrança