Conta, projetos e usuários

O bZapper organiza tudo em três níveis:

Conta (empresa)
 ├── Usuários (admin / membro)        ← faturamento e equipe vivem na conta
 ├── Contatos (compartilhados)        ← visíveis em todos os projetos, filtráveis
 └── Projetos
      ├── Projeto A
      │    ├── Números (instâncias) + rotação
      │    ├── Inbox (conversas/mensagens)
      │    ├── API keys
      │    ├── Estatísticas
      │    └── Identidade dos números (perfil/"Sobre")
      └── Projeto B … (isolado de A)

O que é um projeto?

Um projeto é um ambiente isolado dentro da sua conta. Diferente de outras ferramentas onde "instância = um número", aqui um projeto agrupa vários números que se revezam entre si (redundância). Cada projeto isola:

• Números (instâncias) e a rotação entre eles;
• Inbox — conversas e mensagens;
• API keys;
• Estatísticas (consumo);
• Identidade dos números (perfil/"Sobre").

Use projetos para separar clientes, marcas, ambientes (produção/teste) ou equipes — sem misturar números, conversas nem cobrança.

API keys são por projeto

Cada API key pertence a exatamente um projeto. A chave já carrega o contexto: toda chamada autenticada por ela opera somente nos números, inbox e estatísticas daquele projeto. Não é preciso enviar mais nada.

# Esta key é do "Projeto A" → só vê os números/inbox do Projeto A.
curl https://api.bzapper.com.br/instances -H "Authorization: Bearer bz_live_doProjetoA..."

Para operar em outro projeto, gere uma key naquele projeto (no painel, troque o projeto no seletor do topo e crie a key em Keys).

Painel (sessão de usuário)

No painel, o projeto ativo é escolhido no seletor do cabeçalho e enviado em cada requisição no header X-Project-Id. As telas (Números, Inbox, Keys, Estatísticas) refletem o projeto ativo. Trocar o projeto troca todo o contexto.

Contatos são da conta (compartilhados)

A base de contatos é da conta — o mesmo cliente é reconhecido em qualquer projeto. Você pode filtrar os contatos por projeto:

GET /contacts                      # todos os contatos da conta
GET /contacts?project_id=<id>      # só quem teve conversa naquele projeto
GET /contacts?project_id=current   # só do projeto da sua key/sessão

Usuários e papéis

Usuários pertencem à conta e enxergam todos os projetos. Há dois papéis:

Papel	Pode
Administrador	tudo: faturamento, consumo da conta, gerenciar usuários e projetos
Membro	tudo, exceto faturamento e a página da conta

Um admin convida usuários em Conta → Equipe (por e-mail; o convidado recebe um link para definir a senha). A conta sempre mantém ao menos um administrador.

Faturamento da conta (plano Pro)

O faturamento é da conta (não do projeto): a conta tem um plano (Free ou Pro) e uma moeda, e os recursos de todos os projetos contam contra os limites da conta. O Free é grátis para sempre; o Pro é uma assinatura mensal recorrente (mensagens ilimitadas + um pacote de recursos), com add-ons para ampliar. Detalhes em Cobrança.

A página Cobrança (admin) mostra o plano, as faturas, os cartões (com cartão principal + recorrência) e o consumo agregado por projeto (números, enviadas, recebidas, total).

GET /me/entitlements   # limites efetivos da conta (plano, add-ons, franquias, consumo)
GET /me/subscription   # estado do plano (status, vencimento, recorrência, moeda)
GET /me/invoices       # histórico de faturas da conta
GET /account/usage     # admin: { account: {…}, projects: [{ name, numbers, total, … }] }

Resumo

• Conta = empresa (usuários, faturamento/plano, contatos).
• Projeto = ambiente isolado (números, inbox, keys, stats, identidade).
• API key = sempre de um projeto.
• Contatos = compartilhados, filtráveis por projeto.
• Plano = Free ou Pro (recorrente + add-ons); faturamento vive na conta.
• Membros veem tudo menos faturamento.