> ## Documentation Index
> Fetch the complete documentation index at: https://docs.messagefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Introdução

> Contas são a entidade que agrupa canais, API keys e configurações — entenda a hierarquia e os modelos de uso.

# Administrando Contas

Uma **Conta** (*Account*) representa a entidade principal que agrupa seus canais, chaves de API e
configurações na plataforma MessageFy. Funciona como um **container isolado** para cada projeto,
departamento ou cliente da sua *organization*.

Antes de criar canais ou enviar mensagens, configure pelo menos uma *Account* — todos os demais
recursos (canais, API Keys, mensagens, métricas) vivem dentro de uma *Account* específica.

<Note>
  Ao criar uma *Account*, a plataforma gera automaticamente uma **API Key exclusiva** com prefixo
  `acc_`, já vinculada a essa *Account*. Use essa chave para autenticar as chamadas seguintes
  (criação de canais, conexão de sessão, envio de mensagens etc.).
</Note>

## Hierarquia

```
Organization
├── Account A
│   ├── API Keys
│   ├── Canais (WhatsApp / Webhook)
│   └── Mensagens e métricas
├── Account B
│   ├── API Keys
│   ├── Canais
│   └── Mensagens e métricas
└── ...
```

Cada *Account* é **completamente isolada** das demais. Credenciais, dados e configurações de uma
*Account* não são visíveis nem manipuláveis a partir de outra.

## Para que serve uma Account?

Contas foram projetadas para resolver problemas reais de organização e segurança em empresas que
operam com múltiplos departamentos, times ou clientes:

<AccordionGroup>
  <Accordion title="Segregação de Responsabilidades">
    Cada departamento tem suas próprias credenciais e não pode acessar recursos de outros. O time
    de Vendas não tem acesso aos canais do Suporte, e vice-versa.
  </Accordion>

  <Accordion title="Controle de Acesso por Chave">
    A abrangência de acesso é definida pelo **tipo da API Key**, não por permissões individuais:
    chaves com prefixo `acc_` acessam apenas uma *Account*, enquanto chaves `org_` alcançam toda a
    *Organization*. O limite de uso de cada chave é controlado pelo seu *resourcePlan* (rate limit).
  </Accordion>

  <Accordion title="Métricas Independentes">
    Cada *Account* tem suas próprias métricas. Você pode acompanhar quantas mensagens cada
    departamento enviou, taxa de entrega, tempo de resposta e demais indicadores de forma isolada.
  </Accordion>

  <Accordion title="Faturamento Segmentado">
    Em planos enterprise, é possível ter relatórios de uso e custos separados por *Account*,
    facilitando *chargeback* interno ou análise de ROI por departamento.
  </Accordion>

  <Accordion title="Escalabilidade Organizacional">
    À medida que sua empresa cresce, novas *Accounts* são adicionadas sem afetar as existentes.
    Incluir um novo time ou departamento é simples e não requer reconfiguração dos sistemas já em
    produção.
  </Accordion>
</AccordionGroup>

## Casos de uso

### Caso 1 — E-commerce com múltiplos departamentos

```
Organization: Loja Exemplo LTDA
├── Account: Vendas
│   ├── Canal: WhatsApp (+55 11 98765-0001)
│   └── Webhook: https://api.loja.com/webhooks/vendas
│   Uso: confirmações de pedido, promoções
│
├── Account: Suporte
│   ├── Canal: WhatsApp (+55 11 98765-0002)
│   └── Webhook: https://api.loja.com/webhooks/suporte
│   Uso: atendimento ao cliente, resolução de problemas
│
├── Account: Logística
│   ├── Canal: WhatsApp (+55 11 98765-0003)
│   └── Webhook: https://api.loja.com/webhooks/logistica
│   Uso: notificações de envio, rastreamento
│
└── Account: Marketing
    ├── Canal: WhatsApp (+55 11 98765-0004)
    └── Webhook: https://api.loja.com/webhooks/marketing
    Uso: campanhas, newsletters, remarketing
```

### Caso 2 — Software house com múltiplos clientes

```
Organization: DevHouse LTDA
├── Account: Cliente A — Varejo
│   ├── Canal: WhatsApp (número do cliente A)
│   └── API Key acc_ (isolada nesta Account)
│
├── Account: Cliente B — Saúde
│   ├── Canal: WhatsApp (número do cliente B)
│   └── API Key acc_ (isolada nesta Account)
│
└── Account: Interno — Testes
    ├── Canal: WhatsApp (número de testes)
    └── API Key org_ (acesso a toda a Organization)
```

### Caso 3 — Empresa com filiais

```
Organization: Rede FastFood
├── Account: Filial São Paulo
│   └── Canal: WhatsApp (+55 11 98765-1111)
│
├── Account: Filial Rio de Janeiro
│   └── Canal: WhatsApp (+55 21 98765-2222)
│
└── Account: Filial Belo Horizonte
    └── Canal: WhatsApp (+55 31 98765-3333)
```

## Segurança e isolamento

Cada *Account* é completamente isolada das demais, garantindo:

* **Isolamento de credenciais** — API Keys de uma *Account* não conseguem acessar recursos de outra.
  Se uma chave for comprometida, apenas os recursos daquela *Account* específica ficam em risco.
* **Isolamento de dados** — mensagens, estatísticas e logs são separados por *Account*. O time de
  Vendas não consegue ver mensagens enviadas pelo time de Suporte.
* **Isolamento de configurações** — webhooks, canais e demais configurações são independentes.
  Alterar um webhook na *Account* de Marketing não afeta a *Account* de Vendas.
* **Auditoria granular** — todos os logs e ações são registrados no nível da *Account*, permitindo
  rastreabilidade completa de quem fez o quê e quando.

<Tip>
  **Boa prática de segurança:** nunca compartilhe API Keys entre *Accounts*. Cada departamento deve
  ter suas próprias credenciais — isso facilita a revogação em caso de comprometimento e melhora a
  auditoria.
</Tip>

## Operações disponíveis

<CardGroup cols={2}>
  <Card title="Listar contas" icon="list" href="/api-reference/listar-contas">
    Consulta todas as *Accounts* sob a sua gestão, com filtros e paginação.
  </Card>

  <Card title="Buscar por ID" icon="magnifying-glass" href="/api-reference/obter-conta">
    Recupera os detalhes de uma *Account* específica.
  </Card>

  <Card title="Criar conta" icon="plus" href="/api-reference/criar-conta">
    Cria uma nova *Account* dentro da sua *organization*.
  </Card>

  <Card title="Atualizar conta" icon="pen" href="/api-reference/atualizar-conta">
    Modifica informações de uma *Account* existente.
  </Card>

  <Card title="Deletar conta" icon="trash" href="/api-reference/deletar-conta">
    Remove uma *Account* que não é mais necessária.
  </Card>

  <Card title="Sobre a chave atual" icon="key" href="/api-reference/me">
    Endpoint `/me` que retorna informações sobre a chave de API em uso.
  </Card>
</CardGroup>

<Warning>
  Deletar uma *Account* também invalida suas API Keys e desativa seus canais. Confirme que não há
  recursos em uso antes de remover.
</Warning>