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

# Enviar eventos

> Envie eventos de uso para a Aira via API, interface do Dashboard, planilhas ou integrações.

> Existem quatro formas de enviar eventos para a Aira. A escolha depende do seu caso de uso: integração em tempo real, importação de dados históricos ou testes manuais.

<h2 id="metodos-de-envio">
  Métodos de envio
</h2>

<Tabs>
  <Tab title="Via API">
    O método principal para produção. Sua aplicação envia eventos em tempo real conforme os clientes consomem o produto.

    ```bash theme={null}
    curl -X POST https://api.useaira.com/v1/events/ingest \
      -H "Content-Type: application/json" \
      -H "X-API-KEY: sua_chave_api" \
      -d '{
        "events": [
          {
            "idempotencyKey": "evt-2024-01-15-acme-001",
            "customerExternalId": "acme_001",
            "eventName": "api_request",
            "occurredAt": "2024-01-15T14:30:00Z",
            "properties": {
              "value": 1,
              "endpoint": "/v1/payments",
              "method": "POST"
            }
          }
        ]
      }'
    ```

    <Tip>
      Você pode enviar até **1.000 eventos por requisição**. Não há limite de requisições por minuto, mas recomendamos distribuir o envio ao longo do tempo para evitar picos de processamento.
    </Tip>
  </Tab>

  <Tab title="Via Dashboard">
    Ideal para testes e validações manuais. Acesse **Eventos** no menu lateral e registre eventos individuais diretamente pela interface.

    Use este método para:

    * Testar a configuração de recursos e planos antes de integrar via API
    * Registrar eventos pontuais que não passam pela sua aplicação
    * Validar que o fluxo de faturamento está funcionando corretamente
  </Tab>

  <Tab title="Via Planilhas">
    Ideal para importação de dados históricos ou carga inicial. Faça upload de um arquivo CSV ou Excel com múltiplos eventos de uma vez.

    1. Acesse **Importação de Dados** no Dashboard
    2. Selecione o template **Eventos**
    3. Faça upload do arquivo com as colunas: `chaveIdempotencia`, `idExternoCliente`, `nomeEvento`, `dataOcorrencia`, `valor`
    4. Acompanhe o progresso da importação
  </Tab>

  <Tab title="Via Integrações">
    Use integrações plug-and-play para conectar fontes de dados automaticamente, sem escrever código de integração.

    As integrações disponíveis enviam eventos para a Aira de forma contínua, mantendo os dados de uso sempre atualizados.
  </Tab>
</Tabs>

<br />

<h2 id="transacao-atomica">
  Transação atômica
</h2>

O envio de eventos opera como uma **transação atômica**: se qualquer evento do lote falhar na validação, nenhum evento é processado. Isso garante consistência — não há envio parcial.

<Note>
  Essa é uma decisão importante para integrações: se você enviar 500 eventos e 1 tiver um campo inválido, os 499 válidos também serão rejeitados. Valide os dados antes de enviar ou trate o erro e reenvie o lote corrigido.
</Note>

<br />

<h2 id="boas-praticas">
  Boas práticas
</h2>

* **Use nomes de evento consistentes:** Padronize os nomes de evento (ex: `api_request`, `storage_used`) e documente-os. Recursos dependem do `eventName` para filtrar, e nomes inconsistentes causam dados perdidos.

* **Inclua propriedades úteis para segmentação:** Além do `value`, envie propriedades como `endpoint`, `region`, `plan_tier`. Isso permite criar recursos com filtros granulares sem alterar a integração depois.

* **Capture no nível mais granular possível:** Envie eventos individuais em vez de totais pré-agregados. Deixe os recursos da Aira fazerem a agregação. Isso dá flexibilidade para mudar modelos de precificação no futuro sem alterar a integração.

<br />

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

* [Propriedades e idempotência](/eventos/propriedades-e-idempotencia) — entenda como prevenir duplicatas e usar propriedades para segmentação
* [Recursos](/recursos/visao-geral) — configure como os eventos serão agregados em métricas de cobrança