Skip to main content
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.

​
Métodos de envio

O método principal para produção. Sua aplicação envia eventos em tempo real conforme os clientes consomem o produto.
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"
        }
      }
    ]
  }'
Você pode enviar até 1.000 eventos por requisição. Para volumes maiores, faça múltiplas chamadas ou use a importação via planilha.

​
Transação atômica

O envio de eventos é tudo ou nada: se qualquer evento do lote falhar na validação, nenhum evento é processado. Isso garante consistência — não existe envio parcial.
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.

​
Boas práticas

  • Envie eventos o mais rápido possível — quanto mais próximo do uso real o evento for enviado, mais preciso será o cálculo de cobrança. Evite acumular eventos e enviar tudo de uma vez ao final do dia.
  • Use nomes de evento consistentes — padronize os nomes de evento (ex: api_request, storage_used) e documente-os. Recursos dependem do eventName para filtrar — 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.

​
Próximos passos