# Contas: uma ou várias empresas, só por CNPJ

O OneClick Sales é uma ferramenta para empresas. Cada conta pertence a uma empresa e é identificada pelo CNPJ dela:

- **CPF não é aceito** — nem no cadastro da empresa, nem nesta skill.
- **Um CNPJ, uma conta.** O mesmo CNPJ não fica em duas contas.
- **Filial é outra conta.** Cada filial ou unidade tem CNPJ próprio (final /0002-…, /0003-…) e entra pela
  Organização (Minha Conta › White Label/Organização), que liga as contas do grupo.
- **Subusuários** (a equipe da conta) usam o CNPJ da conta do titular; eles não emitem chaves da API.
- **Empresa sem CNPJ** (pessoa física ou empresa do exterior) não é configurada nesta skill.

## 1. O que a pessoa faz no site (uma vez por empresa)

1. Criar a conta da empresa em https://oneclicksales.com.br/cadastro e completar o cadastro da empresa em
   Minha Conta: razão social, **CNPJ ativo na Receita**, telefone e endereço. Sem isso a API não envia
   (`CADASTRO_INCOMPLETO`).
2. Ter um plano em vigor que inclua a API (https://oneclicksales.com.br/planos).
3. O **titular** da conta abre Minha Conta › Integrações › Chaves de API e cria a chave:
   - **Ambiente:** Sandbox (`ocs_test_pk_…`, simula, para começar) ou Produção (`ocs_live_pk_…`, envia e cobra).
   - **Métodos:** só o que a skill vai usar. Marque sempre **Conta e plano (`account.read`)**: é por ele que a skill
     confere de qual CNPJ é a chave. Lista completa em [metodos.md](metodos.md).
   - **IPs permitidos** (opcional): restringe a chave aos endereços do computador ou servidor que vai usá-la.
   - Dê um nome que diga quem usa a chave (ex.: "Claude – Ana", "Agente de IA – SDR").
4. Copiar a chave na hora (ela aparece uma vez só) e guardá-la como variável de ambiente (abaixo).

## 2. Uma empresa

Duas variáveis: o CNPJ da empresa e a chave dela.

```bash
# macOS / Linux (no ~/.zshrc ou ~/.bashrc)
export OCS_CNPJ="11.222.333/0001-81"
export OCS_API_KEY="ocs_test_pk_SUA_CHAVE"
```

```powershell
# Windows (PowerShell; vale para as próximas janelas e programas abertos depois)
[Environment]::SetEnvironmentVariable('OCS_CNPJ', '11.222.333/0001-81', 'User')
[Environment]::SetEnvironmentVariable('OCS_API_KEY', 'ocs_test_pk_SUA_CHAVE', 'User')
```

O CNPJ pode ir com ou sem pontuação. Depois de criar as variáveis, feche e abra o terminal (e o Claude Code, ou o
aplicativo do agente) para que ele as enxergue.

## 3. Várias pessoas na mesma empresa

Todas usam o mesmo CNPJ. O titular cria **uma chave para cada pessoa ou sistema**, com só os métodos de que ela
precisa — assim dá para ver o uso de cada uma e revogar uma sem parar as outras:

| Quem | Métodos sugeridos |
| --- | --- |
| Quem só acompanha | "Só leitura" (conta, saldo, limites, diagnóstico, status de envios e disparos) |
| Quem envia | leitura + envio dos canais que usa (ex.: `messages.whatsapp.send`, `messages.sms.send`) |
| Quem dispara em massa | leitura + `dispatches.create`, `dispatches.get`, `dispatches.results`, `dispatches.cancel` |
| Financeiro | `account.read`, `account.credits`, `billing.rechargeCredits`, `billing.renewPlan`, `billing.paymentStatus` |

Cada pessoa configura no próprio computador `OCS_CNPJ` (o mesmo para todos) e `OCS_API_KEY` (a chave dela). O teto
de chaves ativas por conta aparece em `GET /v1/account/limits`.

## 4. Várias empresas (grupo, filiais, agência com clientes)

Cada empresa tem a própria conta e a própria chave. Use uma variável por CNPJ, com o CNPJ em 14 dígitos no nome:

```bash
# macOS / Linux
export OCS_API_KEY_11222333000181="ocs_live_pk_CHAVE_DA_MATRIZ"
export OCS_API_KEY_11222333000262="ocs_live_pk_CHAVE_DA_FILIAL"
export OCS_API_KEY_11444777000161="ocs_test_pk_CHAVE_DO_CLIENTE"
```

```powershell
# Windows (PowerShell)
[Environment]::SetEnvironmentVariable('OCS_API_KEY_11222333000181', 'ocs_live_pk_CHAVE_DA_MATRIZ', 'User')
[Environment]::SetEnvironmentVariable('OCS_API_KEY_11444777000161', 'ocs_test_pk_CHAVE_DO_CLIENTE', 'User')
```

- Em cada chamada, diga a empresa com `--cnpj`. Com mais de uma configurada, o script recusa a chamada sem ele.
- A chave de uma empresa nunca age por outra: antes da primeira chamada o script lê `GET /v1/account` e só segue se
  o `account.cnpj` da resposta for o CNPJ da variável.
- Dá para misturar: `OCS_CNPJ` + `OCS_API_KEY` para a empresa principal e `OCS_API_KEY_<CNPJ>` para as outras. O
  mesmo CNPJ com duas chaves diferentes é recusado.
- Agência atendendo clientes: a conta e a chave são **do cliente** (o CNPJ dele, o titular dele). Peça ao cliente que
  emita uma chave com os métodos combinados e entregue por um canal seguro — nunca por e-mail aberto ou chat.

## 5. Conferir

```bash
node scripts/ocs.mjs contas      # CNPJ, ambiente, variável e a chave mascarada (ocs_live_pk_…a1b2)
node scripts/ocs.mjs conferir    # pergunta à API de qual CNPJ é cada chave, o plano e se pode enviar
```

Saída do `conferir` quando está tudo certo:

```text
OK  11.222.333/0001-81  produção  Empresa Exemplo Ltda — plano Plano Profissional Mensal (active); pode enviar
```

| Mensagem | O que fazer |
| --- | --- |
| "parece um CPF" | Use o CNPJ da empresa. A plataforma não aceita CPF. |
| "não é um CNPJ válido" | Confira os 14 dígitos (os dois últimos são verificadores). |
| "a chave em … é da empresa de CNPJ X" | A chave foi colada na variável de outra empresa. Troque. |
| "não tem CNPJ válido no cadastro" | Complete o cadastro da empresa em Minha Conta. |
| `insufficient_scope` | Marque "Conta e plano" (`account.read`) na chave. |
| `unauthorized` | Chave errada, revogada ou com espaço sobrando. Gere outra. |
| `ip_not_allowed` | O IP deste computador não está na lista da chave. |
| `plan_expired` | Plano vencido: a chave só renova (`POST /v1/billing/renew-plan`). |

## 6. Segurança da chave

- A chave dá acesso à conta da empresa: trate como senha. Nunca no chat, em print, no Git ou em arquivo do projeto.
- Prefira começar com a chave de sandbox; troque para produção quando o fluxo estiver certo.
- Saiu da equipe ou suspeita de vazamento: o titular revoga em Minha Conta › Integrações › Chaves de API e cria outra.
- No Claude Code, a variável de ambiente basta; não coloque a chave em `settings.json` de projeto versionado.