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

# Conceitos Fundamentais

> Entenda as entidades centrais da Aira e como elas se conectam para formar um sistema completo de faturamento baseado em uso.

> Antes de começar a usar a Aira, é importante entender como as peças se encaixam. Esta página apresenta os conceitos centrais que formam a base de todo o sistema de faturamento.

<h2 id="visao-geral-da-arquitetura">
  Visão geral da arquitetura
</h2>

A Aira opera em um fluxo linear: dados de uso dos seus clientes entram como **eventos**, são transformados em **métricas** por meio de **recursos**, precificados por **planos** (que pertencem a **produtos**), vinculados a **contratos** e, ao final de cada ciclo, geram **faturas** automaticamente.

<Steps>
  <Step title="Eventos">
    Sua aplicação envia registros de uso para a Aira.
  </Step>

  <Step title="Recursos">
    Eventos são filtrados e agregados em métricas de cobrança.
  </Step>

  <Step title="Produtos e Planos">
    Métricas são associadas a modelos de precificação.
  </Step>

  <Step title="Contratos">
    Planos são vinculados a clientes com ciclos e regras definidas.
  </Step>

  <Step title="Faturas">
    Ao final de cada ciclo, cobranças são calculadas automaticamente.
  </Step>

  <Step title="Pagamentos">
    Faturas são cobradas via PIX, Boleto ou registro manual.
  </Step>
</Steps>

<br />

## Entidades centrais

### Clientes

Clientes são as empresas ou pessoas que consomem seu produto e serão cobradas pela Aira. Cada cliente possui um **ID externo** (definido por você) que conecta o cliente no seu sistema ao cliente na Aira. Clientes podem ser organizados em hierarquias (pai/filho) para cenários como holdings com subsidiárias.

[Saiba mais sobre Clientes →](/clientes/criar-clientes)

### Eventos

Eventos são registros de uso gerados pelos seus clientes. Cada evento captura **quem** usou (ID do cliente), **o que** usou (nome do evento), **quando** usou (timestamp) e **quanto** usou (valor). Eventos são a matéria-prima do faturamento — sem eles, não há como calcular consumo.

[Saiba mais sobre Eventos →](/eventos/visao-geral)

### Recursos

Recursos transformam eventos brutos em métricas de cobrança. Eles definem **quais eventos** participam do cálculo (via filtros) e **como** serão agregados (soma, último do período ou valores únicos). Um mesmo evento pode alimentar múltiplos recursos com filtros diferentes.

[Saiba mais sobre Recursos →](/recursos/visao-geral)

### Produtos

Produtos são agrupadores de planos. Eles representam o que a sua empresa vende — uma plataforma, um serviço, uma solução. Cada plano pertence a um produto, o que permite organizar sua oferta comercial em categorias claras.

### Planos

Planos definem as regras de cobrança: mensalidade fixa, franquia mínima e métricas baseadas em uso. Cada métrica associa um recurso a um modelo de precificação (por unidade, pacote, fixo ou percentual) com faixas de preço. Planos são versionados por contrato — editar o plano original não afeta contratos existentes, e é possível personalizar preços para clientes específicos sem efeitos colaterais.

[Saiba mais sobre Planos →](/planos/criar-planos)

### Contratos

Contratos vinculam **um ou mais planos** a um cliente. Eles definem quando a cobrança começa e termina, o ciclo de faturamento (semanal, mensal ou anual), quais clientes geram uso (escopo) e como reajustes são aplicados. Cada plano dentro do contrato é uma instância independente — quando o plano original é editado, o contrato recebe o status **Desatualizado**; quando personalizado para este cliente, o status **Sobrescrito**.

[Saiba mais sobre Contratos →](/contratos/criar-contratos)

<h3 id="ciclos-de-cobranca">
  Ciclos de Cobrança
</h3>

Ciclos de cobrança são os períodos dentro de um contrato em que o uso é acumulado e cobrado. Por exemplo, um contrato mensal gera um ciclo por mês. Ao final de cada ciclo, a Aira calcula o uso, aplica as regras de precificação e gera uma fatura.

[Saiba mais sobre Ciclos de Cobrança →](/contratos/configuracao-de-cobranca)

### Faturas

Faturas são o resultado final do processo de faturamento. Elas contêm itens de linha detalhados mostrando o consumo por recurso, preços aplicados, descontos e totais. Faturas passam por um ciclo de vida: Aberta → Em Revisão → Emitida → Sincronizada → Paga ou Atrasada. A Aira sincroniza documentos fiscais (NFSe) via ERP e rastreia pagamentos automaticamente.

[Saiba mais sobre Faturas →](/faturas/faturamento-de-clientes)

### Pagamentos

A Aira rastreia pagamentos associados a faturas. Os métodos suportados incluem PIX, Boleto e Bolepix, integrados via gateways de pagamento (Celcash, Omie). Pagamentos podem ser registrados automaticamente por integrações ou manualmente pela equipe financeira.

[Saiba mais sobre Pagamentos →](/pagamentos/metodos-de-pagamento)

### Entidades Legais

Entidades legais representam as empresas (CNPJs) envolvidas no faturamento — tanto a que emite a fatura quanto a que recebe. Cada contrato possui uma **conta de cobrança** (quem emite) e uma **conta de pagamento** (quem recebe), ambas vinculadas a entidades legais. São necessárias para a sincronização de documentos fiscais (NFSe) via ERP.

<h3 id="politicas-de-impostos">
  Políticas de Impostos
</h3>

Políticas de impostos definem as alíquotas e regras de retenção de tributos aplicadas às faturas. Cada contrato referencia uma política, e a Aira avalia as regras automaticamente a cada fatura gerada — incluindo retenções condicionais por valor.

[Saiba mais sobre Políticas de Impostos →](/contratos/politica-de-impostos)

<h3 id="creditos">
  Créditos
</h3>

Créditos são saldos pré-pagos que podem ser aplicados automaticamente a faturas. Funcionam como um pool que é consumido conforme o uso é gerado, reduzindo o valor a pagar. Créditos podem ter data de expiração e são rastreados com histórico completo de transações.

[Saiba mais sobre Créditos →](/creditos/visao-geral)

<br />

## Como as entidades se conectam

<Tabs>
  <Tab title="Fluxo de Faturamento">
    O fluxo principal da Aira segue esta sequência:

    <Steps>
      <Step title="Seu produto gera uso">
        Sua aplicação envia eventos para a Aira toda vez que um cliente consome um recurso (ex: requisição de API, armazenamento, transação).
      </Step>

      <Step title="Recursos agregam o uso">
        Os recursos filtram e agregam os eventos relevantes para cada métrica de cobrança dentro do período do ciclo.
      </Step>

      <Step title="Planos aplicam preços">
        As regras de precificação do plano são aplicadas sobre o valor agregado — por unidade, pacote, fixo ou percentual, com faixas progressivas ou únicas.
      </Step>

      <Step title="Faturas são geradas">
        Ao final do ciclo, a Aira gera uma fatura com itens de linha detalhados, aplica descontos e franquias mínimas, e calcula o total.
      </Step>

      <Step title="Pagamentos são rastreados">
        A fatura é enviada ao cliente e o pagamento é rastreado via integrações de pagamento ou registro manual.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Exemplo Prático">
    Imagine uma empresa de SaaS que cobra por requisições de API:

    1. **Cliente** "Empresa Tech" é cadastrado com ID externo `empresa_tech`
    2. **Eventos** são enviados: `{ eventName: "api_request", customerExternalId: "empresa_tech", value: 1 }`
    3. **Recurso** "Requisições de API" filtra eventos com `eventName = "api_request"` e agrega por soma
    4. **Plano** "Pro" define: `R$ 500`/mês fixo + `R$ 0,01` por requisição acima de 50.000
    5. **Contrato** vincula o plano "Pro" ao cliente "Empresa Tech" com ciclo mensal
    6. **Fatura** ao final do mês: `R$ 500` (fixo) + 30.000 requisições excedentes × `R$ 0,01` = `R$ 800` total
  </Tab>
</Tabs>

<br />

<h2 id="hierarquia-das-entidades">
  Hierarquia das entidades
</h2>

As entidades formam uma cadeia: o uso bruto entra como **evento**, é agregado por um **recurso**, precificado por um **plano**, vinculado a um cliente via **contrato**, materializado a cada ciclo em uma **fatura**, e finalmente liquidado por um **pagamento**. **Produto** e **Cliente** são entidades de referência — outras apontam pra elas mas não as consomem.

```mermaid theme={null}
flowchart LR
    E[Eventos] -->|alimenta| R[Recursos]
    R -->|filtro + agregação| M[Métricas do Plano]
    M --> P[Plano]
    Pr([Produto]) -.->|agrupa| P
    P -->|N instâncias| C[Contrato]
    Cl([Cliente]) -.->|titular| C
    C -->|1 por ciclo| F[Fatura]
    F -->|liquida| Pg[Pagamento]
```

A tabela abaixo resume o que cada entidade contém:

| Entidade  | Composição                                                                            |
| --------- | ------------------------------------------------------------------------------------- |
| Evento    | quem usou, o que usou, quando, quanto                                                 |
| Recurso   | filtros sobre eventos + tipo de agregação                                             |
| Produto   | metadados de integração; agrupa N planos                                              |
| Plano     | mensalidade, franquia e N métricas (cada métrica liga 1 recurso a um modelo de preço) |
| Contrato  | 1 cliente, N planos (instâncias), ciclo de cobrança, escopo de uso                    |
| Fatura    | resultado de 1 ciclo: itens de linha por recurso, totais                              |
| Pagamento | valor, método (PIX/Boleto/Bolepix), gateway, referência                               |

E as cardinalidades-chave entre elas:

* **1 Produto : N Planos** — cada plano pertence a exatamente 1 produto.
* **1 Recurso : N Planos** — o mesmo recurso pode ser precificado em planos diferentes (cada plano define como aquele recurso vira cobrança).
* **1 Cliente : N Contratos** — cada contrato vincula 1 cliente titular.
* **1 Contrato : N Planos** — cada plano dentro do contrato é uma instância independente, capturada no momento do vínculo.
* **1 Contrato : N Faturas** — uma fatura por ciclo de cobrança, não uma por contrato.
* **1 Fatura : 1 Pagamento** (idealmente) — em retentativas após falha do gateway, pode haver N pagamentos pra mesma fatura.

<br />

<h2 id="cenarios-de-uso">
  Cenários de uso
</h2>

A Aira é flexível o suficiente para atender diversos modelos de negócio:

<CardGroup>
  <Card title="SaaS com cobrança por uso" icon="cloud">
    Cobre por requisições de API, usuários ativos, armazenamento ou qualquer métrica mensurável.
  </Card>

  <Card title="Fintechs e meios de pagamento" icon="credit-card">
    Cobre comissões percentuais sobre volume transacionado usando recursos monetários e precificação por basis points.
  </Card>

  <Card title="Plataformas de IA" icon="robot">
    Cobre por tokens processados, minutos de inferência ou chamadas de modelo com faixas de preço progressivas.
  </Card>

  <Card title="Marketplaces e intermediários" icon="store">
    Cobre taxas sobre GMV com split de faturas entre diferentes entidades e subsidiárias.
  </Card>
</CardGroup>

<br />

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

<Card title="Primeiros passos" icon="arrow-right" href="/comece-aqui/primeiros-passos">
  Pronto para começar? Siga o guia de primeiros passos para enviar seu primeiro evento e ver a Aira em ação.
</Card>