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

# Primeiros passos

> Envie seu primeiro evento, configure um recurso e crie um plano. Em poucos minutos, você verá a Aira calculando cobranças automaticamente.

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

<h2 id="antes-de-comecar">
  Antes de começar
</h2>

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

<Steps>
  <Step title="Acesse o Dashboard">
    Entre em [app.useaira.com](https://app.useaira.com) com suas credenciais. Se você ainda não tem acesso, entre em contato com a equipe Aira.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

<br />

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

<Tabs>
  <Tab title="Via Dashboard">
    1. Acesse **Eventos** no menu lateral
    2. Clique em **Novo Evento**
    3. 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`
    4. Clique em **Enviar**
  </Tab>

  <Tab title="Via API">
    ```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_001_api_request",
            "customerExternalId": "cliente_exemplo",
            "eventName": "api_request",
            "occurredAt": "2024-01-15T14:30:00Z",
            "properties": {
              "value": 150
            }
          }
        ]
      }'
    ```
  </Tab>
</Tabs>

<Tip>
  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}`.
</Tip>

<br />

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

<Tabs>
  <Tab title="Via Dashboard">
    1. Acesse **Recursos** no menu lateral
    2. Clique em **Novo Recurso**
    3. Preencha:
       * **Nome:** Requisições de API
       * **Tipo:** Unitário
       * **Agregação:** Soma
       * **Filtro de evento:** `eventName = "api_request"`
    4. Salve o recurso
  </Tab>

  <Tab title="Via API">
    ```bash theme={null}
    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"]
        }
      }'
    ```
  </Tab>
</Tabs>

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

<br />

## 3. Crie um plano

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

<Tabs>
  <Tab title="Via Dashboard">
    1. Acesse **Planos** no menu lateral
    2. Clique em **Novo Plano**
    3. Configure:
       * **Nome:** Plano Starter
       * **Mensalidade:** `R$ 200,00`
       * **Franquia mínima:** `R$ 0,00`
    4. 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
    5. Publique o plano
  </Tab>

  <Tab title="Entendendo 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 |

    <Info>
      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`**.
    </Info>
  </Tab>
</Tabs>

<br />

## 4. Crie um contrato

Vincule o plano ao cliente criando um **contrato**:

<Tabs>
  <Tab title="Via Dashboard">
    1. Acesse **Contratos** no menu lateral
    2. Clique em **Novo Contrato**
    3. Configure:
       * **Cliente:** Selecione o cliente
       * **Planos:** Adicione o Plano Starter
       * **Data de início:** Hoje
       * **Ciclo de cobrança:** Mensal
    4. Ative o contrato
  </Tab>

  <Tab title="O que acontece">
    Ao ativar o contrato, a Aira automaticamente:

    * Cria o primeiro ciclo de cobrança
    * Começa a agregar eventos do cliente neste ciclo
    * Ao final do período, calcula a fatura com base no uso real

    <Tip>
      Você pode acompanhar o uso acumulado do ciclo atual a qualquer momento pelo Dashboard.
    </Tip>
  </Tab>
</Tabs>

<br />

## 5. Acompanhe a fatura

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

<Steps>
  <Step title="Cálculo automático">
    A Aira agrega todos os eventos do período, aplica as regras do plano e calcula cada item de linha.
  </Step>

  <Step title="Revisão">
    A fatura é criada com status **Aberta**. Você pode revisar os itens, ajustar descontos e validar os valores antes de emitir.
  </Step>

  <Step title="Emissão">
    Ao emitir, a Aira gera o PDF da fatura e disponibiliza para o cliente. O documento fiscal (NFSe) é sincronizado automaticamente via ERP.
  </Step>

  <Step title="Pagamento">
    O pagamento é rastreado automaticamente via integrações (PIX, Boleto) ou registrado manualmente pela equipe financeira.
  </Step>
</Steps>

<br />

<h2 id="preparando-para-producao">
  Preparando para produção
</h2>

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](mailto: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.

<br />

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

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

<CardGroup>
  <Card title="Eventos" icon="bolt" href="/eventos/visao-geral">
    Entenda a estrutura completa de eventos, propriedades e boas práticas de envio.
  </Card>

  <Card title="Recursos" icon="cube" href="/recursos/visao-geral">
    Aprenda sobre filtragem, tipos de agregação e recursos unitários vs monetários.
  </Card>

  <Card title="Planos" icon="receipt" href="/planos/criar-planos">
    Explore todos os modelos de precificação, faixas de preço e versionamento.
  </Card>

  <Card title="Referência da API" icon="square-terminal" href="/api-reference/introduction">
    Consulte todos os endpoints disponíveis e exemplos de integração.
  </Card>
</CardGroup>