O AppID da Woovi é uma credencial que identifica sua aplicação e autoriza as chamadas à nossa API. Quem tem essa chave pode agir em nome da sua conta — criar e consultar cobranças, receber webhooks e acessar dados de clientes. Trate o AppID como uma senha do seu ambiente financeiro.

## Regras básicas

* Nunca versione a chave em repositórios de código (Git, GitHub, GitLab), mesmo privados.

* Nunca envie a chave por chat, e-mail, WhatsApp, Slack, ticket de suporte ou planilha compartilhada.

* Nunca cole a chave em ferramentas de IA ou LLMs (ChatGPT, Claude, Copilot, tradutores e formatadores de JSON online). Esse conteúdo pode ser armazenado por terceiros e sai do seu controle.

* Nunca exponha a chave no front-end: JavaScript do navegador, app mobile ou HTML. Toda chamada autenticada deve partir do seu backend.

* Nunca escreva a chave em logs, prints, gravações de tela, documentação interna ou mensagens de erro.

* A equipe da Woovi nunca vai pedir sua API Key. Se alguém pedir, desconfie e nos avise.

## Onde guardar: use um cofre de segredos

Não guarde a chave em arquivo de configuração comum, `.env` commitado, Notion, Google Docs ou gerenciador de senhas pessoal. Use um cofre de segredos, que centraliza o armazenamento, controla quem acessa e registra auditoria:

* HashiCorp Vault

* AWS Secrets Manager ou AWS Systems Manager Parameter Store (SecureString)

* Google Secret Manager

* Azure Key Vault

* Doppler, Infisical ou 1Password Secrets Automation

A aplicação lê o segredo do cofre em tempo de execução (ou o recebe como variável de ambiente injetada no deploy). O valor nunca fica escrito no código nem na imagem do container.

## Criptografia com KMS

Se você precisa armazenar a chave no seu próprio banco ou storage — por exemplo, uma plataforma que guarda credenciais de vários lojistas — criptografe com um KMS (AWS KMS, Google Cloud KMS, Azure Key Vault):

* A chave de criptografia fica no KMS e nunca sai dele.

* Sua aplicação envia o dado para o KMS criptografar/descriptografar (envelope encryption).

* Permissões de `Decrypt` ficam restritas à role específica do serviço que precisa.

* Todo uso fica registrado no log de auditoria do KMS.

Nunca implemente criptografia caseira nem guarde a chave de criptografia junto do dado criptografado.

## Boas práticas operacionais

* **Menor privilégio:** só as pessoas e serviços que realmente precisam devem ter acesso ao segredo.

* **Ambientes separados:** credenciais diferentes para desenvolvimento, homologação e produção. Nunca use a chave de produção para testar.

* **Rotação periódica:** troque a API Key com regularidade e sempre que alguém com acesso sair do time.

* **Logs limpos:** mascare a chave (`app_****`) em qualquer log ou telemetria.

* **Scanner de segredos:** ative detecção de segredos no repositório (GitHub Secret Scanning, gitleaks, trufflehog) e um pre-commit hook.

* **Valide webhooks** pela assinatura recebida, não por segredo embutido na URL.

## Se a sua chave vazou

1. Gere uma nova API Key no painel da Woovi e atualize sua aplicação.

2. Revogue a chave antiga imediatamente.

3. Revise as transações e acessos do período para identificar uso indevido.

4. Se o vazamento foi em um repositório, lembre que remover o commit não basta — o histórico e caches (forks, CI, mirrors) podem manter a chave. Rotacionar é obrigatório.

5. Fale com o suporte da Woovi.