Como começar a usar a API de WhatsApp da StackZap Cloud

Para começar com a API de WhatsApp da StackZap Cloud, você precisa acessar o painel do cliente, abrir o painel do ambiente e conectar uma instância. A infraestrutura do ambiente é gerenciada pela StackLab, enquanto você configura o número e a integração da sua aplicação.

1. 01Acesse sua conta StackZap
2. 02Abra o painel do ambiente
3. 03Crie e conecte uma instância
4. 04Use URL e chave na aplicação

1. Acesse sua conta StackZap

Assine pelo site stackzap.com.br. O pagamento é processado pela Stripe. Após a compra, confira o e-mail enviado com os dados de acesso e entre em contas.stacklab.digital. Os dados são específicos da sua conta e dos ambientes provisionados; mantenha-os privados.

2. Abra o painel do ambiente

No painel de cliente, selecione o ambiente que deseja usar. Cada ambiente tem sua própria API, banco de dados, endereço e credencial. Copie a URL exibida nesse painel para configurar sua aplicação. A URL de exemplos na documentação é apenas ilustrativa e não substitui o endereço individual do seu ambiente.

3. Crie e conecte uma instância

No painel do ambiente, escolha Criar instância, informe um nome que ajude a identificar a operação e siga o fluxo de conexão. Você poderá parear o WhatsApp pelo QR Code ou pelo código de conexão, conforme a opção disponível no painel. O artigo como conectar pelo QR Code ou código detalha esse passo.

Antes de iniciar: reúna os itens necessários

Separe o acesso ao e-mail usado na assinatura, o painel do cliente, o telefone que será pareado e o sistema que pretende integrar. Para fazer chamadas, você também precisará da URL do ambiente, do ID da instância e da API Key. Os dados são específicos de cada ambiente; não use as credenciais de um tutorial ou de outro projeto.

Decida quem será responsável pela configuração e por eventuais mensagens. A pessoa que administra o painel deve ter autorização para parear o número e guardar os dados de acesso. Se mais de uma pessoa participa, combine onde as credenciais serão armazenadas e como um acesso será removido quando alguém deixar a equipe.

O provisionamento informado para Cloud é em média de cinco segundos após a confirmação do pagamento. É uma média, não um tempo garantido nem um SLA. A conclusão do provisionamento significa que o ambiente está criado; a conexão do WhatsApp ainda é uma etapa separada que você faz no painel.

Compreenda conta, ambiente e instância

O painel de cliente em contas.stacklab.digital centraliza o acesso aos ambientes comprados. Cada ambiente tem uma API e um banco próprios, além de uma URL própria. Dentro do painel do ambiente, você administra uma ou mais instâncias de WhatsApp de acordo com a disponibilidade do plano.

Esses três elementos resolvem problemas diferentes. A conta permite encontrar e administrar os ambientes. O ambiente delimita a API, o banco e as credenciais daquela operação. A instância representa a conexão com uma conta WhatsApp. Uma chave de API não deve ser confundida com uma senha de acesso ao painel; mantenha cada uma no lugar correto.

Antes de copiar dados, confirme o nome ou o identificador do ambiente selecionado. Se você tem desenvolvimento e produção, anote essa diferença em sua documentação interna. Uma chamada de teste feita na URL errada pode enviar dados ao número de produção ou consultar um conjunto de instâncias diferente.

Como os três níveis se relacionam

Acesso inicial ao Cloud

Depois de assinar pelo site, observe seu e-mail e use os dados de acesso recebidos para entrar no painel do cliente. Se a mensagem não chegar, confira a pasta de spam e se o endereço digitado no checkout está correto. Não encaminhe a mensagem de credenciais por um canal sem proteção; salve a informação em um cofre de acesso apropriado.

Ao entrar, confira a lista de ambientes disponíveis e abra o correto. Antes de prosseguir, valide que o plano exibido e o nome do ambiente correspondem ao que sua equipe espera. Se algo estiver ausente ou diferente, não crie diversos ambientes para tentar corrigir por conta própria; entre em contato pelo widget do painel ou canal de suporte informado.

Crie uma instância com um nome operacional

Clique em Criar instância e escolha um nome que identifique claramente o propósito, sem conter informação pessoal ou segredo. Exemplos de critérios podem ser operação, equipe ou ambiente: “atendimento”, “pedidos” ou “teste”. Evite nomes vagos como “principal2” ou “WhatsApp novo”, que confundem quando o projeto cresce.

Se você planeja integrar o sistema com várias conexões, registre os nomes e IDs em um inventário interno. Defina quem é responsável por cada uma e quais automações podem usá-la. O número de instâncias disponíveis depende do plano Cloud, portanto confira a página de planos antes de criar conexões que sua assinatura não comporta.

Pareie o número com cuidado

O painel oferece o fluxo para conectar pelo QR Code ou código de pareamento. Tenha acesso ao aplicativo no telefone autorizado e conclua a confirmação no menu de dispositivos conectados. Não envie QR, código ou tela do pareamento a outra pessoa para que faça a leitura fora do procedimento esperado.

Quando o painel indicar que a conexão terminou, confirme o estado da instância. Se o aplicativo pedir uma nova autorização, leia a mensagem antes de seguir. Não tente parear repetidamente sem entender o resultado de cada tentativa; códigos antigos podem expirar e uma conexão diferente pode ficar associada à instância.

Para passos detalhados, use o artigo como conectar pelo QR Code ou código de pareamento. Se você usa self-hosted, o processo técnico segue a configuração publicada nos manuais StackZap.

Localize dados da API sem expor credenciais

No painel do ambiente, identifique URL base e API Key. A URL pode ser parecida com o padrão do ambiente, mas o domínio real depende da configuração; copie o valor que o painel mostra. Não troque pelo exemplo genérico https://api.stackzap.com exibido em materiais antigos ou em outra referência se essa não for a URL da sua conta.

Guarde a chave no backend, por secret manager ou mecanismo equivalente. Evite colá-la em planilha, documento público, mensagem instantânea ou arquivo JavaScript entregue ao navegador. Se precisar compartilhar com uma pessoa da equipe, use o cofre da organização e limite o acesso a quem realmente desenvolve ou opera a integração.

Faça uma consulta simples à API antes de disparar mensagens. A primeira chamada permite conferir se o domínio resolve, o certificado HTTPS está válido, o ID pertence ao ambiente e a autenticação está funcionando. Se receber um erro, preserve a mensagem da API e remova a chave antes de compartilhá-la.

Integre um fluxo mínimo primeiro

Escolha apenas uma tarefa inicial, como enviar uma mensagem de confirmação para um número de teste autorizado. Aplique a credencial no header documentado, valide o corpo JSON e inspecione o resultado HTTP e a resposta. Não comece com uma campanha automática, lista de contatos real ou integração simultânea com vários sistemas.

Depois valide a parte de entrada: configure um webhook de teste se seu caso precisa receber mensagens ou atualizações. A rota pública deve operar em HTTPS, preservar o corpo original para validar HMAC, responder com sucesso rapidamente e evitar processar a mesma entrega duas vezes. Registre o delivery_id e o resultado do processamento.

Quando os dois sentidos estiverem comprovados, expanda passo a passo para CRM, Chatwoot, ERP ou automação. Separe a configuração por ambiente, use logs sem segredos e tenha um procedimento para pausar o envio em caso de erro ou de solicitação de interrupção.

Entenda o que está incluído no plano

Os planos Cloud diferem em número de instâncias e capacidade de armazenar ou enviar mídias. O limite de armazenamento é diferente das cotas diárias de upload e volume enviado. Um backup não consome a cota diária de upload conforme informado pelo produto, mas mídia e backup ocupam o armazenamento compartilhado. Confirme a página comercial atual antes de dimensionar.

Não presuma que limite de upload seja um limite de mensagens de texto. Também não suponha que o armazenamento fique vazio quando uma cota diária renova. A página Planos e o painel do seu ambiente mostram informações mais atuais do que um artigo que pode ter sido lido depois de uma alteração de produto.

Segurança do primeiro acesso

Após obter acesso, troque ou proteja a senha do painel conforme as opções disponíveis. Restrinja o acesso ao painel e à URL de API, mantenha dispositivos da equipe protegidos e registre quem tem permissão para administrar as instâncias. Remova usuários que não trabalham mais na operação e trate credenciais expostas como potencialmente comprometidas.

Ao abrir um chamado, informe ambiente, ID da instância, horário e status observado. O suporte não precisa receber a chave completa, QR Code ou código de pareamento para entender uma primeira falha. Se alguém pedir esses dados em um canal público, interrompa o envio e confirme o canal oficial pelo painel.

Problemas comuns no primeiro acesso

Não encontrei o e-mail. Confirme o endereço usado na compra, filtre spam e promoções e aguarde a conclusão do pagamento. Depois, contate o suporte sem compartilhar dados de cartão.

Entrei, mas não aparece o ambiente. Verifique se está na conta associada à compra. Guarde captura sem dados pessoais e informe ao suporte o e-mail da conta e o horário, sem expor credenciais.

Não sei qual URL usar. Copie do painel do ambiente selecionado. Cada ambiente tem endereço próprio e um endereço de exemplo pode não funcionar para sua assinatura.

A chamada retorna 401. Confirme o header e que a API Key é daquele ambiente. Masque a chave ao revisar logs.

A instância não conecta. Gere código atualizado, use o menu atual do WhatsApp e verifique o estado no painel. Se persistir, envie ao suporte apenas o identificador e horário do erro.

Checklist para seu primeiro dia

• A compra aparece como confirmada e o e-mail de acesso corresponde à conta certa.
• Você selecionou o ambiente correto no painel do cliente.
• A URL e a API Key vieram do painel desse mesmo ambiente.
• A instância foi criada com um nome que sua equipe consegue reconhecer.
• O número foi pareado e o estado observado antes de começar os envios.
• Uma consulta e uma mensagem de teste funcionaram sem publicar segredos.
• Sua aplicação mantém chave e webhook secret protegidos.
• A equipe sabe pausar a automação e encontrar o suporte.

Quando essas etapas estiverem concluídas, avance para o artigo de autenticação das chamadas e para a referência oficial da API.

4. Faça uma chamada de API

Use a URL e a API Key do ambiente junto aos endpoints documentados. Guarde a credencial em um secret manager ou variável de ambiente no servidor da sua aplicação. Não coloque a chave em JavaScript público, aplicativo distribuído ou repositório aberto.

Antes de automatizar envios, faça uma chamada controlada e confirme a resposta da API e o estado da instância. Para exemplos completos, consulte a referência oficial. O StackZap Cloud cuida da infraestrutura; a configuração de destinatários, mensagens e integrações continua sendo responsabilidade de quem opera a aplicação.

Faça seu primeiro teste em três partes

Primeiro valide conectividade: chame um endpoint de leitura com a URL e API Key do ambiente novo. Depois confirme a instância e o status no painel. Por fim, faça uma mensagem curta para um número de teste autorizado. Registre a resposta e o horário. Esse caminho permite identificar se o problema está na URL, autenticação, sessão ou operação de envio, em vez de alterar tudo ao mesmo tempo.

Antes de passar para produção, documente qual aplicação usa a chave, onde está armazenada e quem recebe alertas. Defina um procedimento para rotacionar a credencial e para pausar envios se a instância desconectar. Mesmo um piloto precisa de um destinatário que espera a mensagem e de um método para impedir duplicidade.

Ao concluir o primeiro teste, compartilhe com a equipe um resumo sem credenciais: qual ambiente foi usado, qual operação foi validada e quais etapas faltam para produção. Essa documentação reduz dependência de quem fez a configuração e torna a revisão posterior mais objetiva. Guarde o comando de exemplo com placeholders e registre que a API Key deve ser carregada apenas no backend.