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

# Propriedades e idempotência

> Use propriedades adicionais para segmentar eventos e chaves de idempotência para prevenir duplicatas.

> 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

```json theme={null}
{
  "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:

<Frame>
  <img src="https://mintcdn.com/aira-e93056c6/D0DI4R_7r28AeG1L/static/event-properties.png?fit=max&auto=format&n=D0DI4R_7r28AeG1L&q=85&s=777bee60b2d657c10b7d75d9f351eddd" alt="Propriedades de um evento no Dashboard da Aira" width="4012" height="2338" data-path="static/event-properties.png" />
</Frame>

### O campo `value`

O campo `value` dentro de `properties` é **obrigatório** em todo evento. Ele representa a quantidade consumida naquela ação:

| Cenário                | Valor de `value` | Significado                 |
| ---------------------- | ---------------- | --------------------------- |
| Requisição de API      | `1`              | Uma requisição              |
| Armazenamento          | `50`             | 50 GB                       |
| Transação financeira   | `150000`         | `R$ 1.500,00` (em centavos) |
| Horas de processamento | `4`              | 4 horas (inteiro)           |

<Note>
  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.
</Note>

<br />

<h2 id="idempotencia">
  Idempotência
</h2>

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.

<Info>
  A unicidade da chave é **por tenant** — cada workspace tem seu próprio espaço de chaves. Não há conflito entre tenants diferentes.
</Info>

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

<h2 id="proximos-passos">
  Próximos passos
</h2>

* [Enviar eventos](/eventos/enviar-eventos) — veja os diferentes métodos de envio
* [Recursos](/recursos/visao-geral) — entenda como eventos são filtrados e agregados para cobrança