Skip to main content

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.

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. Não há limite de requisições por minuto, mas recomendamos distribuir o envio ao longo do tempo para evitar picos de processamento.

​
Transação atômica

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

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

​
Próximos passos

  • Propriedades e idempotência — entenda como prevenir duplicatas e usar propriedades para segmentação
  • Recursos — configure como os eventos serão agregados em métricas de cobrança