Chamadas protegidas da API de WhatsApp da StackZap exigem uma credencial. A referência técnica documenta o header X-API-Key; envie a chave no cabeçalho HTTPS de cada requisição protegida. No StackZap Cloud, use a chave e a URL exibidas no painel do ambiente que fará a operação.

Exemplo de chamada

curl -X GET "https://SEU-AMBIENTE/v1/instances" \
  -H "**X-API-Key**: ${STACKZAP_API_KEY}" \
  -H "Accept: application/json"

Substitua https://SEU-AMBIENTE pela URL real do seu ambiente e carregue STACKZAP_API_KEY de um cofre de segredos ou variável protegida no servidor. Não cole a credencial literal em scripts compartilhados, capturas de tela ou páginas web públicas.

Onde encontrar a URL e a chave

No Cloud, abra contas.stacklab.digital, selecione o ambiente e consulte os dados próprios dele. Cada ambiente tem endereço e credenciais específicos. Para uma instalação self-hosted, utilize o domínio configurado pelo operador e as credenciais geradas para aquela instalação.

Cada request autenticado precisa dos dados do ambiente
  1. 01URL base do ambiente
  2. 02Endpoint e ID da instância
  3. 03Header X-API-Key
  4. 04Resposta JSON da API

Erros comuns de autenticação

  • 401 Unauthorized: confira se o header está presente e se o valor corresponde ao ambiente chamado.
  • 403 Forbidden: a credencial pode não ter permissão para a operação ou escopo solicitado; consulte a resposta e a documentação.
  • URL incorreta: confirme protocolo HTTPS, domínio e caminho do endpoint.
  • Chave exposta: remova a credencial do local público e siga o procedimento de revogação/rotação disponível no seu painel ou instalação. Se não encontrar essa ação, peça orientação ao suporte.

Em logs, registre o status HTTP, o endpoint e um identificador de requisição quando houver. Masculhe a chave e outros dados pessoais antes de enviar um diagnóstico. Confira métodos de autenticação aceitos pela sua versão na documentação da API.

Como organizar a configuração por ambiente

Separe as configurações de desenvolvimento, homologação e produção. Cada ambiente StackZap Cloud possui seu próprio endereço e credenciais. Por isso, mantenha pares independentes de URL e API Key, identificados sem ambiguidades, por exemplo STACKZAP_BASE_URL_STAGING e STACKZAP_API_KEY_STAGING. Em produção, use variáveis equivalentes fornecidas pelo gerenciador de segredos da sua plataforma. Evite reaproveitar uma chave de homologação só porque o código já está configurado.

Carregue os valores em tempo de execução. Em aplicações web, a API Key deve permanecer no servidor: valores incluídos em JavaScript enviado ao navegador podem ser lidos pelo usuário. Um fluxo comum é o navegador chamar seu backend autenticado, e o backend chamar a API StackZap. Para um script operacional, injete o segredo por variável protegida ou cofre, limite quem pode visualizar os logs da execução e apague a variável do ambiente quando ela deixar de ser necessária.

Antes de fazer uma requisição, valide que a URL base corresponde ao ambiente esperado. Um mecanismo simples é impedir que uma aplicação de teste use uma URL de produção, ou exigir confirmação explícita para executar ações reais. Registre o nome lógico do ambiente, não a chave. Essa separação evita tanto o erro de credencial inválida quanto o envio acidental de mensagens a partir da instância errada.

Exemplo com JavaScript no servidor

O código a seguir mostra a estrutura da chamada no Node.js. O endpoint e o corpo devem ser confirmados na documentação da versão utilizada; os valores entre colchetes são placeholders, não URLs reais:

const baseUrl = process.env.STACKZAP_BASE_URL;
const apiKey = process.env.STACKZAP_API_KEY;
const instanceId = process.env.STACKZAP_INSTANCE_ID;

if (!baseUrl || !apiKey || !instanceId) {
  throw new Error("Configure URL, chave e instância StackZap");
}

const response = await fetch(
  `${baseUrl}/v1/instances/${instanceId}/status`,
  { headers: { "X-API-Key": apiKey, "Accept": "application/json" } }
);

if (!response.ok) {
  throw new Error(`StackZap respondeu HTTP ${response.status}`);
}

const status = await response.json();

Esse trecho ilustra a montagem segura de headers e o tratamento do status HTTP. Confirme o caminho real da operação na referência técnica; não copie endpoints de outro ambiente sem verificar se a versão e os recursos coincidem. Em particular, nunca use esse código no navegador com apiKey embutida num bundle público.

O header precisa chegar intacto

Alguns proxies, gateways e funções serverless removem headers não reconhecidos ou transformam nomes. Se a chamada funciona localmente, mas retorna não autorizado em produção, verifique se X-API-Key está sendo encaminhado. A maioria das bibliotecas HTTP trata nomes de headers sem diferenciar maiúsculas e minúsculas, mas um intermediário customizado pode ter regras próprias.

Confirme também que o valor não contém espaços adicionados pela configuração, que não está sendo enviado como Bearer ... quando a API espera o valor direto e que o cliente não envia a chave no corpo ou na query string. O header correto reduz o risco de aparecer em históricos de URL e registros de proxy. Use HTTPS para proteger a comunicação entre sua aplicação e o endpoint do ambiente.

Diagnóstico de 401, 403 e erros de conexão

Um 401 Unauthorized costuma indicar credencial ausente ou inválida. Confira o nome exato do header, a variável de ambiente carregada, o espaço em branco no valor e se a chave pertence à URL chamada. Evite imprimir a chave inteira para verificar. Se precisar comparar configuração, registre apenas se ela está definida e, no máximo, uma impressão digital não reversível calculada localmente sob processo controlado.

Um 403 Forbidden pode indicar uma operação não permitida ou política de autorização. Leia a resposta conforme a documentação e confirme se a operação está habilitada para aquela instância. Não tente contornar a restrição usando outra chave sem entender o motivo. Em caso de dúvida, envie ao suporte o ambiente, o endpoint, o horário, o status HTTP e o identificador de requisição, nunca o segredo.

Um erro de DNS, timeout ou conexão recusada geralmente ocorre antes de a API avaliar a chave. Confira domínio, HTTPS, resolução DNS e regras de saída da sua infraestrutura. Compare a URL copiada do painel com a configurada no serviço e confira se não duplicou ou removeu um segmento de caminho. Um timeout não significa que a chave está errada; diagnostique transporte e autenticação em etapas separadas.

Rotação e resposta a vazamento

Se uma chave aparecer em repositório público, ticket, captura, log acessível ou código de cliente, trate-a como comprometida. Remova a exposição, avalie a atividade recente associada, substitua a credencial conforme os recursos disponíveis na sua instalação e atualize os serviços dependentes. Se o painel não oferecer uma ação de revogação ou rotação, contate o suporte e siga as instruções específicas. Apagar uma chave do arquivo atual não remove cópias em commits antigos ou backups.

Faça rotação planejada quando mudar um responsável ou serviço, durante desligamentos de integrações e como parte da política de segurança da empresa. Uma troca segura considera dependências: implante a nova configuração, valide chamadas autorizadas e então invalide a antiga quando o procedimento permitir. Evite deixar duas chaves amplamente distribuídas por tempo indeterminado. Documente o responsável e a data, nunca o valor da credencial.

Logs úteis sem segredos

Um log de integração deve ajudar a reproduzir o problema sem revelar credenciais nem conteúdo sensível. Registre o método, o caminho sem query secreta, o status, a duração, o nome do ambiente, o identificador da instância e um request ID quando disponível. Mascare números de telefone e corpos de mensagens de acordo com sua necessidade operacional e base legal. Não habilite logs de headers completos em produção.

ambiente=producao operacao=consultar_status instancia=inst_abc
http_status=401 duracao_ms=84 request_id=req_123
api_key=[redigida] telefone=[redigido]

O exemplo não pretende definir um formato oficial; mostra o princípio de correlacionar a falha sem copiar o segredo. Se enviar logs ao suporte, reduza o período ao necessário e confira o arquivo antes de anexá-lo. Uma credencial pode ser exposta por um dump aparentemente inocente ou por um comando curl copiado do terminal.

Lista de verificação antes de colocar em produção

  • A URL foi copiada do ambiente correto e usa HTTPS.
  • A API Key pertence a esse mesmo ambiente.
  • A chave está em um cofre ou configuração privada do servidor.
  • O header X-API-Key chega ao endpoint sem alterações.
  • A chamada não aparece em código, HTML, aplicativo cliente ou query string.
  • Logs e rastreamentos ocultam credenciais e conteúdo não necessário.
  • Erros distinguem autenticação, autorização e falha de rede.
  • Um procedimento de rotação e resposta a exposição está definido.

Esse cuidado é especialmente importante em projetos com agentes de IA. Uma instrução enviada ao modelo pode influenciar o texto e as operações que ele solicita, mas a credencial deve ficar fora do contexto do modelo sempre que possível. Encapsule as operações permitidas num backend e valide os parâmetros antes de chamar a StackZap. A documentação da API lista os recursos disponíveis; sua aplicação deve limitar o que cada usuário ou agente pode executar.

Valide configuração na inicialização

Falhar cedo ajuda a evitar chamadas para ambiente errado. Ao iniciar o serviço, confira que a URL usa HTTPS em produção, que a chave está definida e que o ID da instância está configurado. Não registre os valores completos no erro; informe somente qual configuração está ausente. Se a validação falhar, não habilite o worker de envio.

Mantenha uma tabela de configuração por ambiente e injete os valores pelo gerenciador de deployment. Em desenvolvimento local, use uma credencial de teste com acesso controlado; nunca copie um .env de produção para uma máquina compartilhada. Ao promover uma versão, atualize secrets no destino e confirme que o serviço realmente carregou a nova configuração.

Audite operações sensíveis

Além de autenticar o request na StackZap, autentique usuários da sua própria aplicação. Uma API Key de serviço pode ter mais alcance do que qualquer usuário individual; o backend precisa aplicar regras de negócio e registrar quem iniciou uma ação. Para mensagens, grave identificador do operador ou automação, finalidade, instância e resultado técnico, evitando armazenar conteúdo sem necessidade.

Em caso de 401, não faça retry em alta velocidade. Pare o fluxo, confira ambiente e variável carregada e alerte o responsável. Em caso de 403, determine se a operação está autorizada. Uma chave válida não deve se tornar permissão irrestrita para qualquer usuário do seu sistema.

Configure rotação no deploy

Inclua atualização de secrets no checklist de release e verifique o valor carregado sem exibi-lo. Um serviço pode continuar usando um secret antigo até ser reiniciado; planeje a ordem e confira logs de autenticação depois do deploy. Se a chave está armazenada em mais de um serviço, mantenha inventário e atualize todos os consumidores autorizados.

Ensaie a rotação em homologação com credenciais próprias. Confirme quais erros aparecem quando o valor é inválido e se sua aplicação interrompe retries em vez de gerar tráfego repetido. Não misture esse teste com rotação de produção.

Confirme o destino da requisição

Em ambientes com proxy, confira o host final, certificado, DNS e caminho que realmente chegaram ao serviço. Uma aplicação pode ter header correto e ainda chamar outro ambiente. Use logs de rede sanitizados ou endpoint de diagnóstico permitido, sem registrar o segredo. Se testar com curl, leia a API Key de variável protegida e não compartilhe a linha literal do terminal.

Cuidado com ambientes de preview

Pull requests e deploys temporários podem executar código com permissões de rede e logs. Não compartilhe API Key de produção com previews públicos nem com contribuições ainda não revisadas. Use credenciais de teste e restrinja o que esse ambiente consegue alcançar. Ao encerrar um preview, remova secrets temporários e confirme que os serviços foram desligados.

Se usuários acessam seu próprio painel, nunca envie a chave StackZap na resposta do backend apenas para a interface fazer chamadas diretas. Crie endpoints específicos e valide autorização em cada um. O backend deve escolher a credencial com base no tenant autenticado, não num campo de texto recebido do cliente.

Faça chamadas somente do serviço autorizado

Centralize o acesso à API em um serviço backend e limite quais módulos podem importar o cliente autenticado. Essa separação reduz a chance de uma chave ser copiada para frontend, logs ou integração sem revisão. Se um serviço deixar de usar a StackZap, remova sua variável e confirme que não há workers antigos em execução. Mantenha registro de ambiente, responsável e última revisão da credencial, sem armazenar seu valor em documentação.