Enviar eventos

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

Via API
Via Dashboard
Via Planilhas
Via Integrações

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 de 1 a 10.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.

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.

Acesse Importação de Dados no Dashboard
Selecione o template Eventos
Faça upload do arquivo com as colunas: chaveIdempotencia, idExternoCliente, nomeEvento, dataOcorrencia, valor
Acompanhe o progresso da importação

Transação atômica

O envio de eventos opera como uma transação atômica: se qualquer evento do lote falhar ao ser processado, nenhum evento é gravado. 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 erro, os 499 válidos também serão rejeitados. Valide os dados antes de enviar ou trate o erro apontado na resposta e reenvie o lote corrigido.

Resposta de erro

Quando o lote falha, a resposta traz o erro geral (message e code) e, em details, os erros encontrados ao processar cada evento, identificado pela sua idempotencyKey:

{
  "message": "failed to create events",
  "code": "failed_to_create_events",
  "details": [
    {
      "idempotencyKey": "evt-2024-01-15-acme-001",
      "errors": [
        {
          "code": "future_occurred_at",
          "message": "events occurring in the future cannot be recorded"
        }
      ]
    }
  ]
}

Os códigos possíveis por evento:

Código	Significado
`future_occurred_at`	O `occurredAt` do evento está no futuro
`duplicated_idempotency_key`	Já existe um evento com esta chave de idempotência
`failed_on_previous_event_creation`	O evento não foi gravado porque outro evento do lote falhou — corrija o evento com erro e reenvie o lote
`immutable_field_change`	O envio altera campos imutáveis de um evento já gravado com esta chave

Veja o formato completo em Respostas de erro. O envio de saldos de licenças segue exatamente a mesma regra de lote. Veja Reportar saldos.

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

​Métodos de envio

​Transação atômica

​Resposta de erro

​Boas práticas

​Próximos passos

Métodos de envio

Transação atômica

Resposta de erro

Boas práticas

Próximos passos