Primeiros Passos

Siga este guia para configurar seu primeiro fluxo de faturamento na Aira. Ao final, você terá eventos sendo enviados, um recurso agregando uso e um plano calculando cobranças.

Antes de começar

Certifique-se de que você tem acesso ao Dashboard:

Acesse o Dashboard

Entre em app.useaira.com com suas credenciais. Se você ainda não tem acesso, entre em contato com a equipe Aira.

Cadastre um cliente de teste

Em Clientes, crie um cliente com um nome e ID externo de teste (ex: cliente_teste). Esse será o cliente que receberá os eventos nos passos seguintes.

Recomendamos que você siga este guia usando dados de teste antes de configurar clientes e planos reais. Isso permite validar todo o fluxo de faturamento sem impactar a operação.

1. Envie seu primeiro evento

Eventos representam o uso que seus clientes fazem do seu produto. Envie um evento informando qual cliente usou, o que usou e quanto:

Via Dashboard
Via API

Acesse Eventos no menu lateral
Clique em Novo Evento
Preencha os campos:
- Chave de idempotência: evt_001_api_request
- ID externo do cliente: cliente_exemplo
- Nome do evento: api_request
- Data de ocorrência: selecione a data e hora
- Valor: 150
Clique em Enviar

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_001_api_request",
        "customerExternalId": "cliente_exemplo",
        "eventName": "api_request",
        "occurredAt": "2024-01-15T14:30:00Z",
        "properties": {
          "value": 150
        }
      }
    ]
  }'

A idempotencyKey garante que o mesmo evento não será processado duas vezes, mesmo que você envie a requisição mais de uma vez. Use uma combinação única como {data}_{cliente}_{evento}.

2. Crie um recurso

Com eventos sendo enviados, o próximo passo é criar um recurso que define como esses eventos serão agregados para cobrança.

Via Dashboard
Via API

Acesse Recursos no menu lateral
Clique em Novo Recurso
Preencha:
- Nome: Requisições de API
- Tipo: Unitário
- Agregação: Soma
- Filtro de evento: eventName = "api_request"
Salve o recurso

curl -X POST https://api.useaira.com/v1/resources/ \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: sua_chave_api" \
  -d '{
    "name": "Requisições de API",
    "type": "unit",
    "aggregation": "sum",
    "filters": {
      "eventName": ["api_request"]
    }
  }'

O recurso define quais eventos contam e como são somados. No exemplo acima, todos os eventos com eventName = "api_request" serão somados no período.

3. Crie um plano

Agora, crie um plano que define quanto cobrar pelo uso medido pelo recurso.

Via Dashboard
Entendendo o plano

Acesse Planos no menu lateral
Clique em Novo Plano
Configure:
- Nome: Plano Starter
- Mensalidade: R$ 200,00
- Franquia mínima: R$ 0,00
Adicione uma métrica:
- Recurso: Requisições de API
- Modelo: Unitário
- Faixas de preço:
  - Até 10.000 unidades → R$ 0,00 (incluso)
  - Acima de 10.000 → R$ 0,005 por unidade
Publique o plano

Neste exemplo, o plano funciona assim:

Componente	Valor
Mensalidade fixa	`R$ 200,00`/mês
Primeiras 10.000 requisições	Incluso
Requisições excedentes	`R$ 0,005` por unidade

Se o cliente fizer 25.000 requisições no mês, a fatura será: R$ 200 (fixo) + 15.000 × R$ 0,005 (excedente) = R$ 275,00.

4. Crie um contrato

Vincule o plano ao cliente criando um contrato:

Via Dashboard
O que acontece

Acesse Contratos no menu lateral
Clique em Novo Contrato
Configure:
- Cliente: Selecione o cliente
- Planos: Adicione o Plano Starter
- Data de início: Hoje
- Ciclo de cobrança: Mensal
Ative o contrato

5. Acompanhe a fatura

Ao final do ciclo de cobrança, a Aira gera a fatura automaticamente:

Cálculo automático

A Aira agrega todos os eventos do período, aplica as regras do plano e calcula cada item de linha.

Revisão

A fatura é criada com status Aberta. Você pode revisar os itens, ajustar descontos e validar os valores antes de emitir.

Emissão

Ao emitir, a Aira gera o PDF da fatura e disponibiliza para o cliente. O documento fiscal (NFSe) é sincronizado automaticamente via ERP.

Pagamento

O pagamento é rastreado automaticamente via integrações (PIX, Boleto) ou registrado manualmente pela equipe financeira.

Preparando para produção

Depois de validar o fluxo com dados de teste, prepare o ambiente para uso real:

Configure suas entidades legais: Em Configurações, cadastre as entidades legais (CNPJs) que emitirão faturas e receberão pagamentos. Isso é necessário para criar contratos e para a sincronização de documentos fiscais via ERP.
Configure integrações: Se você usa Omie (ERP) ou Celcash (pagamentos), solicite a ativação ao time da Aira em contato@useaira.com enviando as credenciais correspondentes. Isso habilita a sincronização automática de faturas, NFSe e cobranças via PIX/Boleto.
Convide sua equipe: Em Configurações → Usuários, convide os membros da equipe que precisam acessar o Dashboard. A Aira suporta diferentes níveis de permissão (administrador, escrita, leitura).
Cadastre seus clientes reais: Importe seus clientes via Dashboard ou API. Use IDs externos consistentes com o que sua aplicação já utiliza para facilitar o envio de eventos.
Integre o envio de eventos: Configure sua aplicação para enviar eventos automaticamente à Aira via API. Valide que os eventos estão chegando corretamente antes de criar contratos de produção.

Próximos passos

Agora que você entende o fluxo básico, explore cada conceito em profundidade:

Eventos

Entenda a estrutura completa de eventos, propriedades e boas práticas de envio.

Recursos

Aprenda sobre filtragem, tipos de agregação e recursos unitários vs monetários.

Planos

Explore todos os modelos de precificação, faixas de preço e versionamento.

Referência da API

Consulte todos os endpoints disponíveis e exemplos de integração.

Guias

​Antes de começar

​1. Envie seu primeiro evento

​2. Crie um recurso

​3. Crie um plano

​4. Crie um contrato

​5. Acompanhe a fatura

​Preparando para produção

​Próximos passos

Eventos

Recursos

Planos

Referência da API

Antes de começar

1. Envie seu primeiro evento

2. Crie um recurso

3. Crie um plano

4. Crie um contrato

5. Acompanhe a fatura

Preparando para produção

Próximos passos