# Conta, limites, créditos, cobrança e números

Tudo aqui é leitura, menos a cobrança Pix e a conexão de número (marcadas). Com a chave de sandbox as leituras
devolvem o dado real da conta; cobrança e conexão de número são recusadas (403 `test_key_not_allowed`).

## Conta e plano

- `GET /v1` (toda chave): o ambiente da chave, os métodos que ela pode chamar e os limites dela.
- `GET /v1/account` (`account.read`): `account` (razão social, nome fantasia, **`cnpj`** com 14 dígitos, situação),
  `plan` (nome, ciclo, `status`: `active`, `expiring` — vence em até 7 dias —, `expired` ou `none`; `expiresAt`,
  `daysRemaining`), `billingProfile` (cadastro da empresa completo e o que falta) e `sending` (`allowed` e `blockedBy`).
- Plano vencido: a chave recebe 403 `plan_expired` em tudo, menos na renovação e no status do Pix dela.

## Limites e diagnóstico

- `GET /v1/account/limits` (`account.limits`): chamadas por minuto (leitura, alteração, envio) e por dia com o uso de
  hoje, chaves ativas e o teto (`activeKeys`, `maxKeys`), a janela de envio aberta agora e a próxima abertura, uma
  abordagem por dia por contato em cada canal, os tetos do disparo em massa e o limite diário de cada número de
  WhatsApp pela idade dele.
- `GET /v1/account/health` (`account.health`): `status` `ok`, `warning` ou `critical` e a lista `checks` — plano,
  cadastro, saldo, números de WhatsApp, webhook, campanhas pausadas e erros da API de hoje, com a ação sugerida.
  Comece por aqui quando algo "não funciona".
- `GET /v1/account/api-usage?days=7` (`account.apiUsage`, 1 a 90 dias): chamadas, sucessos, erros e recusas por
  limite, por dia, método e chave.
- `GET /v1/account/api-errors?limit=50` (`account.apiErrors`, até 200; `&key=current` só desta chave): as últimas
  chamadas com erro (código, mensagem e `requestId`), guardadas por 30 dias.

## Créditos

`GET /v1/account/credits` (`account.credits`): saldo por carteira em `balances`. As carteiras de `valueChannels`
(voz, vídeo, contatos) estão em reais; as outras, em unidades (1 = um envio). Carteiras: `wa` (WhatsApp), `sms`,
`email`, `voice`, `video_ia`, `video_avatar`, `contatos` e as do robô.

Os créditos comprados valem 90 dias e só podem ser usados com o plano em dia. Preços em vigor:
https://oneclicksales.com.br/planos — nunca informe preço de memória.

## Cobrança por Pix (altera: produção, `--confirmado`)

- `POST /v1/billing/recharge-credits` (`billing.rechargeCredits`):
  `{ "items": [{ "channel": "whatsapp", "qty": 1000 }, { "channel": "sms", "qty": 500 }] }` — `channel`: `whatsapp`,
  `sms`, `email`, `voice`, `video`, `video_avatar`; `qty` inteiro de 1 a 100.000.
- `POST /v1/billing/renew-plan` (`billing.renewPlan`): `{ "plan": "mensal" | "anual", "tier": "<plano>" }`. Sem
  `plan`, vale o ciclo atual; sem `tier`, renova o plano atual. Funciona com o plano vencido.
- As duas respondem `201` com `paymentId`, `amountBrl`, `pix.copyPaste` (Pix copia e cola), `pix.qrCodeBase64`,
  `pix.expiresAt` e `statusUrl`. Quem paga é a pessoa, no app do banco: mostre o valor e o "copia e cola" e nunca
  diga que está pago antes de conferir.
- `GET /v1/billing/payments/{paymentId}` (`billing.paymentStatus`): `status` e `paid`. Consulte a cada 5 a 10 s
  enquanto a pessoa paga; com `paid: true`, plano ou créditos estão liberados.

## Números de WhatsApp

- `GET /v1/channels` (`channels.list`): os números da conta, com `instanceName`, `phone`, `connected` e `status`.
- `POST /v1/channels/add-number` (`channels.addNumber`; altera — produção, `--confirmado`): `{ "mode": "qr" }`
  devolve o `qrCode` para a pessoa escanear no WhatsApp do número; `{ "mode": "pairing_code", "phone": "55…" }`
  devolve um código para digitar. Depois, `GET /v1/channels` mostra quando conectou.