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

# Visão geral

> Eventos são registros de uso gerados pelos seus clientes. Eles são a base de todo o faturamento baseado em uso na Aira.

> Cada evento registra uma ação de consumo feita por um cliente — e é a partir deles que toda a cadeia de cobrança é calculada.

<Frame>
  <img src="https://mintcdn.com/aira-e93056c6/D0DI4R_7r28AeG1L/static/event-list.png?fit=max&auto=format&n=D0DI4R_7r28AeG1L&q=85&s=50acb8da6749d43d50971215487e60aa" alt="Aira — Listagem de eventos" width="4072" height="2404" data-path="static/event-list.png" />
</Frame>

<h2 id="o-que-sao-eventos">
  O que são eventos
</h2>

Um evento é um registro que documenta uma ação de uso realizada por um cliente no seu produto. Pense nele como um recibo digital: ele registra **quem** usou, **o que** usou, **quando** usou e **quanto** usou.

Exemplos do mundo real:

| Produto           | Evento                  | O que mede                           |
| ----------------- | ----------------------- | ------------------------------------ |
| Plataforma de API | `api_request`           | Cada chamada à API                   |
| Cloud storage     | `storage_used`          | GB armazenados por dia               |
| Fintech           | `transaction_processed` | Cada transação financeira processada |
| Plataforma de IA  | `inference_call`        | Cada chamada de inferência ao modelo |
| Help desk         | `ticket_resolved`       | Cada ticket resolvido                |

<br />

## Estrutura de um evento

Cada evento possui os seguintes campos:

| Campo                | Obrigatório | Descrição                                               |
| -------------------- | ----------- | ------------------------------------------------------- |
| `idempotencyKey`     | Sim         | Chave única que previne processamento duplicado         |
| `customerExternalId` | Sim         | ID externo do cliente que gerou o uso                   |
| `eventName`          | Sim         | Nome do tipo de uso (ex: `api_request`, `storage_used`) |
| `occurredAt`         | Sim         | Quando o uso aconteceu (ISO 8601, UTC)                  |
| `properties.value`   | Sim         | Quantidade consumida (inteiro, mínimo 0)                |
| `properties.*`       | Não         | Propriedades adicionais para filtragem e segmentação    |

```json theme={null}
{
  "idempotencyKey": "20240115-acme-api-req-001",
  "customerExternalId": "acme_001",
  "eventName": "api_request",
  "occurredAt": "2024-01-15T14:30:00Z",
  "properties": {
    "value": 250,
    "endpoint": "/v1/payments",
    "method": "POST",
    "status_code": 200
  }
}
```

<Note>
  Para recursos monetários (valores em dinheiro), envie o valor em **centavos** — por exemplo, `R$ 1.200,50` deve ser enviado como `120050`.
</Note>

<br />

<h2 id="origem-do-evento">
  Origem do evento
</h2>

Cada evento registra automaticamente como foi criado:

| Origem     | Quando                                          |
| ---------- | ----------------------------------------------- |
| **API**    | Evento enviado via endpoint `/v1/events/ingest` |
| **Import** | Evento importado via planilha CSV/Excel         |
| **User**   | Evento criado manualmente pelo Dashboard        |

Essa informação é útil para auditoria e rastreabilidade.

<br />

<h2 id="recalculo-de-faturas">
  Recálculo de faturas
</h2>

As faturas são recalculadas diariamente durante a madrugada com os eventos recebidos ao longo do dia. Depois que uma fatura é fechada, ela não é recalculada automaticamente — apenas por ação manual no Dashboard.

<Info>
  Se você precisa corrigir eventos após o fechamento de uma fatura, é possível reabrir a fatura e recalcular os valores manualmente.
</Info>

<br />

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

* [Enviar eventos](/eventos/enviar-eventos) — aprenda as diferentes formas de enviar eventos para a Aira
* [Propriedades e idempotência](/eventos/propriedades-e-idempotencia) — entenda como usar propriedades adicionais e prevenir duplicatas
* [Recursos](/recursos/visao-geral) — veja como eventos são transformados em métricas de cobrança