Como conectar o WhatsApp à API pelo QR Code ou código de pareamento

Para usar a API de WhatsApp da StackZap, primeiro conecte uma conta a uma instância. A conexão é feita pelo mecanismo de dispositivos vinculados do WhatsApp: você confirma o pareamento no aplicativo do celular usando um QR Code ou código de conexão disponível no seu painel.

Conectar pelo painel StackZap Cloud

1. Entre em contas.stacklab.digital e abra o painel do ambiente correto.
2. Clique em Criar instância e informe um nome de identificação.
3. Escolha o método de conexão apresentado pelo painel.
4. No celular que controla a conta, abra as configurações do WhatsApp e entre em Dispositivos conectados.
5. Toque em Conectar dispositivo e conclua o pareamento indicado na tela.
6. Aguarde a atualização do estado da instância no painel.

Os nomes e a posição dos menus no aplicativo podem variar conforme versão e sistema. Use o procedimento que o WhatsApp mostra no próprio celular.

Conectar pela API self-hosted

Na instalação própria, o fluxo depende da configuração do servidor e das ferramentas instaladas. A API documenta operações para criar instâncias, iniciar a conexão, obter o QR e consultar o estado. Confira os endpoints e exemplos atuais na referência técnica; não reutilize credenciais de demonstração em produção.

Se o QR Code expirar

Um QR Code pode expirar antes de ser escaneado. Gere ou solicite um código novo pelo painel/API e tente novamente. Evite publicar ou enviar capturas do QR Code a outras pessoas: ele participa do pareamento da sessão. Se a tela não atualizar, consulte o estado da instância e siga as opções de reconexão documentadas.

QR Code e código de pareamento

Os dois métodos concluem o vínculo do dispositivo, mas a apresentação é diferente. O QR Code é lido com a câmera pelo fluxo de dispositivos conectados. No método de código, o painel apresenta um valor para inserir no aplicativo. Use a tela do seu ambiente como fonte para os passos exatos; não compartilhe esse código durante o atendimento.

QR Code

Abra Dispositivos conectados no celular e leia o QR Code atual apresentado pela StackZap.

Código de pareamento

Solicite um código no painel e informe-o no fluxo de conexão do WhatsApp.

Depois de conectar, confira o estado antes de enviar mensagens e mantenha o celular e a conta sob controle do responsável autorizado. Se o pareamento falhar repetidamente, registre o horário e a mensagem de erro, sem enviar QR, código ou chave, e contate o suporte StackZap.

Prepare a conta antes de iniciar

Antes de abrir o QR Code, confirme que está usando a conta correta no celular. Em equipes, registre quem é responsável pelo número, quem pode aprovar novas sessões e qual ambiente receberá os eventos. Essa checagem evita conectar um número de atendimento ao ambiente de testes ou parear um telefone pessoal por engano.

Confira também a conectividade do celular e do computador. O telefone precisa conseguir usar o WhatsApp, e o navegador precisa alcançar o painel. Se o ambiente acabou de ser criado, aguarde o painel terminar o provisionamento e só então solicite o código. Abra uma tentativa por vez: solicitar vários códigos em sequência dificulta saber qual QR continua válido. Use sempre o mais recente exibido pelo ambiente.

No Cloud, escolha a instância dentro do ambiente certo. Cada ambiente tem URL, banco e API próprios; uma instância conectada em um ambiente não fica automaticamente disponível em outro. No self-hosted, verifique se está no endereço e instalação corretos. Guarde essa identificação nos registros operacionais, mas não guarde QR Codes ou códigos de pareamento como dados permanentes.

Entenda as etapas da conexão

O pareamento pode ser entendido como uma sequência de quatro estados: a instância é criada, a conexão é solicitada, o WhatsApp confirma o dispositivo e a API passa a indicar que a sessão está pronta. A interface pode usar rótulos diferentes; use o indicador atual exibido pelo painel e consulte o manual da versão ao automatizar o fluxo.

1. 01Criar a instância no ambiente correto
2. 02Solicitar QR Code ou código atualizado
3. 03Confirmar o vínculo no WhatsApp do celular
4. 04Consultar o estado antes de fazer chamadas

Não considere o simples aparecimento do QR como conclusão. Ele representa uma solicitação pendente. A confirmação acontece no aplicativo, e a API precisa refletir que a sessão está conectada antes de aceitar operações dependentes dela. Uma integração deve consultar o estado com intervalo razoável e limite de tentativas, em vez de repetir uma chamada num loop sem pausa.

Quando usar QR Code ou código de pareamento

Use QR Code quando o fluxo do painel o oferecer e o celular puder ler a imagem diretamente. O código de pareamento pode ser conveniente quando o WhatsApp orienta a vinculação por código digitado ou quando a câmera não está disponível. A disponibilidade depende do fluxo apresentado pela versão em uso; não assuma que toda instalação terá os dois ao mesmo tempo.

Em ambos os casos, proteja a tela. Um QR ou código recém-gerado é temporário e participa da autorização de um dispositivo. Não o inclua em tickets públicos, gravações de tela ou mensagens em grupo. Se precisar de ajuda, compartilhe o horário, a etapa em que parou e o texto do erro, ocultando códigos e dados pessoais.

Escolha o método disponível no painel

A disponibilidade e os nomes das opções podem variar conforme o fluxo apresentado.

O QR não aparece ou não é lido

Verifique se a instância terminou de ser criada e se o painel está aberto na instância correta. Atualize a tela uma vez e solicite um novo QR se o anterior expirou. Aumente o brilho do celular, limpe a lente, evite reflexos e ajuste a distância até a câmera focar. Não tente ler uma captura antiga salva na galeria: a sessão pode já ter sido renovada.

Se a imagem aparecer cortada, confira o zoom do navegador, a escala do sistema e o tamanho da janela. Em telas estreitas, role o painel para localizar as ações de conexão; não use os controles de outra instância por engano. Em rede corporativa, verifique se proxy ou regras de bloqueio impedem o painel de carregar componentes. Se outras páginas também falharem, registre o problema como possível falha de acesso, não como erro de pareamento.

Quando o aplicativo informa que o código expirou, volte ao painel e gere outro. Quando informa que o dispositivo já está conectado ou que o limite de dispositivos foi atingido, revise os dispositivos vinculados na conta pelo próprio WhatsApp e remova sessões desconhecidas ou obsoletas conforme a política da empresa. Não use a StackZap para contornar controles de segurança da conta.

Faça um teste pequeno depois de conectar

Valide a sessão antes de ligar automações. Consulte o estado da instância, confirme que sua aplicação aponta para a URL desse ambiente e envie uma mensagem de teste para um número controlado pela equipe, com autorização para recebê-la. Evite iniciar uma campanha ou importar uma lista como primeiro teste. Isso ajuda a separar falhas de conexão, configuração e lógica da aplicação.

Se a API ainda indicar desconectado, espere a atualização documentada e consulte novamente. Compare horário e identificador da instância em todos os passos. Não crie várias instâncias com nomes semelhantes para tentar resolver uma sessão: isso pode tornar a origem dos eventos e mensagens ambígua. Prefira nomes que indiquem finalidade e estágio, como suporte-producao e integracao-homologacao, sem dados pessoais.

Reparear ou trocar o número

Trocar o número associado exige tratar a sessão anterior como uma conexão diferente. Antes da mudança, pause automações para que nenhuma fila continue enviando para a conta antiga. Confirme a política interna de migração, remova credenciais antigas dos sistemas que não devem mais operar e faça o novo pareamento pelo fluxo suportado no painel. Atualize consumidores de webhook, valide o estado e faça um envio controlado.

Não presuma que recriar a instância migra histórico, configuração ou identificadores automaticamente. O comportamento depende do produto e da versão, e os dados locais podem continuar ligados ao ambiente anterior. Consulte a documentação da API e os procedimentos do operador antes de apagar ou recriar recursos. No Cloud, o suporte pelo widget do ambiente ou pelo WhatsApp pode orientar a leitura do estado; nunca envie sua API Key no pedido.

Checklist de diagnóstico

• Instância inexistente: confirme que terminou a criação e anote o identificador correto.
• QR expirado: gere um código novo e descarte o anterior.
• Leitura falha: confira foco, brilho, reflexo e se o QR pertence à tentativa atual.
• Pareamento confirmado, mas estado não mudou: atualize uma vez, consulte novamente e registre horários.
• Conta com dispositivo desconhecido: revise a segurança no WhatsApp antes de continuar.
• API retorna desconectado: pause envios automáticos e verifique sessão e endpoint.
• Problema persiste: informe ambiente, instância, horário, etapa e mensagem de erro, sem segredos.

Esse registro ajuda a equipe técnica a distinguir um código expirado de uma falha de rede ou de uma chamada direcionada ao ambiente errado. A documentação técnica da StackZap é a fonte para parâmetros e endpoints específicos da versão instalada.

Cuide da conta vinculada

O número conectado deve pertencer à empresa ou à pessoa responsável pelo canal e permanecer sob controle de alguém autorizado a administrar dispositivos vinculados. Antes de usar um telefone de funcionário, combine o que acontece se essa pessoa sair, trocar aparelho ou perder acesso. Um processo de conexão não substitui a governança da linha telefônica nem a recuperação da conta no WhatsApp.

Revise periodicamente os dispositivos vinculados no aplicativo e remova acessos que não reconhece. Se um dispositivo for removido, consulte o estado da instância e interrompa automações até entender se é necessário parear novamente. Evite compartilhar o telefone principal entre muitos operadores; defina responsáveis e use os perfis de acesso da sua organização.

Diferença entre parear e autorizar mensagens

O pareamento vincula uma sessão técnica à conta. Ele não importa uma lista de contatos nem constitui autorização para enviar qualquer conteúdo. A finalidade, a expectativa e a preferência do destinatário devem ser tratadas no sistema de negócio. Concluir o QR apenas deixa a conexão disponível para as operações documentadas.

Após conectar, confira se o canal exibido no painel corresponde à finalidade planejada. Uma mensagem de teste deve explicar o contexto e ser enviada a alguém que concordou em participar. Se o número for de produção, evite experimentos de texto, mídia ou retry diretamente com clientes.

Pareamento em uma equipe

Defina quem pode visualizar o QR e quem confirma a ação no celular. Faça a conexão em uma sessão de trabalho controlada, sem gravação de tela e sem compartilhar link público. Ao finalizar, registre data, ambiente, ID e responsável, mas não guarde uma captura do código. Se o time precisar de acesso, conceda o painel apropriado em vez de distribuir credenciais pessoais.

Quando um projeto tem vários números, conecte e valide um por vez. Dê nomes diferentes às instâncias e confira cada estado. Essa disciplina evita que um QR de uma instância seja lido para outra e simplifica a auditoria posterior.

Quando o celular não está disponível

O pareamento depende de confirmação pela conta no aplicativo. Se o responsável pelo celular não está disponível, aguarde em vez de compartilhar código com outra pessoa ou tentar contornar a confirmação. Coordene o horário com quem administra o número e mantenha a tela de conexão fechada até a pessoa poder completar a etapa. Essa dependência deve entrar no plano de operação e na escala de suporte.

Se for necessário substituir o aparelho, atualize primeiro o acesso à conta pelo procedimento oficial do WhatsApp. Só depois reavalie a sessão StackZap. A equipe deve saber quem pode recuperar o número e como evitar que a linha seja perdida numa troca de funcionário.

Combine quem administra o número

Inclua o pareamento no procedimento de entrada e saída de funcionários. O responsável pela linha deve saber em quais ambientes ela está conectada e como remover um dispositivo desconhecido. Ao transferir a responsabilidade, revise o acesso à conta e confirme a sessão no painel. Não deixe o QR aberto enquanto a equipe tenta encontrar alguém autorizado, nem salve uma imagem para usar mais tarde: solicite um novo código quando o responsável estiver disponível.