> ## 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.
# Criar clientes
> Cadastre clientes na Aira para associá-los a contratos, eventos de uso e faturas.
> Clientes são as empresas ou pessoas que consomem o seu produto e serão cobradas pela Aira. Todo o fluxo de faturamento começa com um cliente cadastrado.
O que é um cliente na Aira
Um cliente representa a entidade que será faturada. Ele é o elo entre os eventos de uso gerados pela sua aplicação e as faturas emitidas pela Aira. Sem um cliente cadastrado, não é possível criar contratos, enviar eventos nem gerar cobranças.
Cada cliente possui um **ID externo** — um identificador definido por você que conecta o cliente no seu sistema ao cliente na Aira. Quando sua aplicação envia eventos de uso, ela referencia o cliente pelo ID externo, e a Aira sabe a quem atribuir o consumo.
Use o mesmo identificador que você já utiliza no seu sistema (ex: `tenant_id`, `account_id`, `org_123`). Isso simplifica a integração e evita mapeamentos adicionais.
## Criar um cliente
1. Acesse **Clientes** no menu lateral
2. Clique em **Novo Cliente**
3. Preencha os dados do cliente:
* **Nome** — nome da empresa ou pessoa
* **ID Externo** — identificador único no seu sistema
* **Tipo** — Individual, Subsidiária ou Organização
4. Opcionalmente, cadastre uma **conta de pagamento** com os dados fiscais:
* Razão social, nome fantasia, CNPJ/CPF
* Endereço completo (CEP, rua, número, bairro, cidade, estado)
* E-mails de contato financeiro
5. Salve o cliente
```bash theme={null}
curl -X POST https://api.useaira.com/v1/customers/ \
-H "Content-Type: application/json" \
-H "X-API-KEY: sua_chave_api" \
-d '{
"name": "Acme Tecnologia Ltda",
"externalId": "acme_001",
"type": "individual"
}'
```
## Campos do cliente
| Campo | Obrigatório | Editável | Descrição |
| --------------------- | ----------- | -------- | ------------------------------------------------------------------------------------------------- |
| Nome | Sim | Sim | Nome de exibição do cliente |
| ID Externo | Sim | **Não** | Identificador único no seu sistema, usado para vincular eventos |
| Tipo | Sim | **Não** | Individual, Subsidiária ou Organização |
| Prefixo de fatura | Automático | **Não** | Código de 5 caracteres gerado a partir do nome, usado na numeração de faturas (ex: `ACMET-00001`) |
| Campos personalizados | Não | Sim | Metadados adicionais (texto ou lista de textos) |
**ID Externo**, **Tipo** e **Prefixo de fatura** são imutáveis após a criação. O prefixo é gerado automaticamente pela Aira com base no nome do cliente e garante unicidade na numeração de faturas.
## Conta de pagamento
Ao criar um cliente, você pode opcionalmente cadastrar uma **conta de pagamento** — ela armazena os dados fiscais e legais usados nas faturas:
* **Razão social e nome fantasia**
* **CNPJ ou CPF** (com validação de unicidade)
* **Endereço completo** (usado em documentos fiscais)
* **E-mails** para envio de faturas e cobranças
Um cliente pode ter múltiplas contas de pagamento (ex: diferentes CNPJs para diferentes filiais). A conta de pagamento é vinculada ao contrato na hora de configurar as alocações de faturamento.
Régua de cobrança
A [régua de cobrança](/faturas/regua-de-cobranca) define os e-mails que o cliente recebe sobre suas faturas — do aviso de emissão aos lembretes de vencimento. Ao criar um cliente, a Aira atribui automaticamente a **régua padrão** do workspace, se houver uma configurada.
Um cliente **sem régua atribuída não recebe nenhum e-mail de cobrança** — nem o de emissão da fatura. A régua padrão é definida em **Réguas de cobrança → Configurações de cobrança**; trocá-la depois não reatribui os clientes que já existem.
## Gerenciar clientes
### Arquivar clientes
Arquivar é uma exclusão lógica — o cliente é marcado como inativo, mas todo o histórico (contratos, faturas, eventos) é preservado para consulta e relatórios.
**Restrições para arquivar:**
* **Individual ou Organização:** Não pode ter contratos ativos ou em rascunho. Todos os contratos precisam estar cancelados ou completos.
* **Subsidiária:** Não pode estar sendo usada em alocações de nenhum contrato.
* **Organização:** Ao arquivar, todas as subsidiárias não arquivadas são arquivadas automaticamente.
Clientes arquivados podem ser **desarquivados** a qualquer momento, restaurando-os para o estado ativo.
### Excluir clientes
Além de arquivar, é possível **excluir permanentemente** um cliente. A exclusão remove o cliente e faz cascata em todos os dados vinculados (contratos, ciclos de cobrança, faturas, contas de pagamento).
A exclusão só é permitida se o cliente não tiver faturas em status emitido ou posterior (Emitida, Sincronizada, Paga, Atrasada). Faturas em Aberta, Em Revisão ou Cancelada são removidas junto. **Esta ação é irreversível.**
Próximos passos
* [Tipos e hierarquias](/clientes/tipos-e-hierarquias) — entenda a diferença entre Individual, Subsidiária e Organização
* [Régua de cobrança](/faturas/regua-de-cobranca) — os e-mails de cobrança que o cliente recebe
* [Portal do cliente](/clientes/portal-do-cliente) — disponibilize um portal para seus clientes acessarem faturas e métricas
* [Eventos](/eventos/visao-geral) — comece a enviar eventos de uso associados aos seus clientes
* [Contratos](/contratos/criar-contratos) — vincule planos a clientes para iniciar o faturamento