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 rotacionam entre si (anti-ban). 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 (carteira pré-paga)

O faturamento é da conta (não do projeto) e é pré-pago pay-as-you-go: não há planos fixos nem assinatura. A conta tem uma carteira com saldo (dinheiro pago + bônus de cortesia), e o consumo de todos os projetos é debitado dela. Há uma franquia grátis para sempre por pilar (mensagens, números, storage, projetos) — só o excedente cobra. Detalhes em Cobrança (pré-pago).

A página Conta (admin) mostra o saldo da carteira, as recargas, a auto-recarga (cartão salvo + limiar) e os tetos de gasto, além do consumo agregado por projeto (números, enviadas, recebidas, total).

GET /me/entitlements   # limites efetivos da conta + carteira + rate card + tetos
GET /billing/wallet    # saldo (pago + bônus) + extrato recente
GET /account/usage     # admin: { account: {…}, projects: [{ name, numbers, total, … }] }

Resumo

• Conta = empresa (usuários, faturamento/carteira, contatos).
• Projeto = ambiente isolado (números, inbox, keys, stats, identidade).
• API key = sempre de um projeto.
• Contatos = compartilhados, filtráveis por projeto.
• Carteira = pré-paga (pago + bônus), recargas e auto-recarga vivem na conta.
• Membros veem tudo menos faturamento.