QR Code do WhatsApp não aparece na API: o que checar

A instância é criada e fica no estado PENDING até ser pareada. Para parear, você pede o QR em QR Code da instância e lê com o celular em Aparelhos conectados, como no WhatsApp Web. Quando a instância ainda não está conectada, a resposta traz o QR no campo instance.qrcode. O QR é de curta duração: se passar do tempo, peça outro em vez de insistir no antigo.

Se a instância já está conectada, a API não gera QR. Ela confirma o estado e devolve connected como verdadeiro, com o status da instância. Isso pega muita gente: o painel ou seu código espera uma imagem e recebe um objeto de status. Antes de depurar qualquer outra coisa, olhe o status da instância.

BASE="https://api.zapzapapi.com/api/v1"
H1="x-api-key: $ZAPZAP_API_KEY"
H2="x-api-secret: $ZAPZAP_API_SECRET"

# 1) estado atual: disconnected, connecting ou connected
curl "$BASE/$INSTANCE_ID/instance/status" -H "$H1" -H "$H2"

# 2) QR code (só vem se a instância ainda não estiver conectada)
curl "$BASE/instances/$INSTANCE_ID/qrcode" -H "$H1" -H "$H2"

const fs = require("fs");
const BASE = "https://api.zapzapapi.com/api/v1";
const headers = {
  "x-api-key": process.env.ZAPZAP_API_KEY,
  "x-api-secret": process.env.ZAPZAP_API_SECRET,
};

async function main() {
  const id = process.env.INSTANCE_ID;
  const resp = await fetch(BASE + "/instances/" + id + "/qrcode", { headers });
  const corpo = await resp.json();

  if (!resp.ok) {
    console.error("erro", resp.status, corpo.error, corpo.message);
    return;
  }
  if (corpo.connected) {
    console.log("já conectada:", corpo.instance && corpo.instance.status);
    return;
  }
  const qr = corpo.instance && corpo.instance.qrcode;
  if (!qr) {
    console.log("sem QR ainda, tente de novo:", JSON.stringify(corpo));
    return;
  }
  const base64 = qr.replace(/^data:image\/\w+;base64,/, "");
  fs.writeFileSync("qr.png", Buffer.from(base64, "base64"));
  console.log("QR salvo em qr.png, leia com o celular");
}
main();

Tabela de diagnóstico para a chamada de QR code. As mensagens abaixo são as que a API devolve no corpo da resposta.

Dois detalhes de integração. O ID no caminho é o ID da instância, não o nome nem o telefone. E o 409 aparece quando seu código chama o QR em loop apertado: a API trava a geração por instância por um curto período para evitar QR sobreposto. Faça polling com intervalo de alguns segundos, não em rajada.

Primeiro, confira se o QR foi renderizado inteiro. O campo qrcode é uma imagem em base64 e, se o seu front corta o prefixo ou usa um elemento de tamanho pequeno, a leitura falha. Exiba a imagem em tamanho grande, com fundo branco e sem filtro de dark mode invertendo as cores.

Segundo, o celular precisa estar com o WhatsApp atualizado e com internet. Abra Configurações, Aparelhos conectados, Conectar um aparelho. Se o celular já está no limite de aparelhos conectados, remova um antes. Terceiro, QR expirado: gere um novo e leia logo. Se o fluxo estiver numa tela sua, atualize o QR de tempos em tempos enquanto o status não for connected.

Se mesmo assim a leitura falha, use o pareamento por código, que não depende de câmera.

A chamada conectar instância aceita o campo phone. Com o telefone no formato internacional (DDI, DDD e número, só dígitos), a API gera um código de pareamento em vez de QR. No celular, vá em Aparelhos conectados, Conectar um aparelho, e escolha conectar com número de telefone, digitando o código exibido. Sem o campo phone, a chamada gera o QR.

A API valida o formato do telefone e devolve erro de validação para número com símbolos ou sem código do país. O código vem em instance.paircode na resposta. Gere o código só quando for usá-lo, porque uma nova geração substitui a anterior.

curl -X POST "https://api.zapzapapi.com/api/v1/$INSTANCE_ID/instance/connect" \
  -H "x-api-key: $ZAPZAP_API_KEY" \
  -H "x-api-secret: $ZAPZAP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"phone":"5511999999999"}'
# digite no celular o código recebido em instance.paircode

Se a leitura do QR funciona mas a instância volta a desconectar logo em seguida, o problema deixou de ser o QR. Veja o guia de WhatsApp que desconecta sozinho na API. Se o WhatsApp recusa parear o número, ele pode estar restrito pelo próprio WhatsApp; o caminho é o do guia número banido: o que fazer.

Para criar a instância e conectar passo a passo, o início rápido mostra o fluxo completo, e a página de API de WhatsApp lista os endpoints de instância. O custo por número ativo está em preços.

[ ] Criei a instância e tenho o ID correto (não o nome nem o telefone)

[ ] O status da instância não é connected quando peço o QR

[ ] Há saldo suficiente e a instância não está suspensa ou bloqueada

[ ] Faço uma chamada de QR por vez e espero alguns segundos entre as tentativas

[ ] O QR é exibido por inteiro, em tamanho grande e com fundo branco

[ ] O WhatsApp do celular está atualizado e com internet

[ ] Se a câmera falha, uso o pareamento por código com o telefone em formato internacional

Em interfaces para clientes finais, vale mostrar instruções passo a passo ao lado do QR (abrir o WhatsApp, Aparelhos conectados, Conectar um aparelho) e um botão para gerar outro QR. Atualize o QR automaticamente enquanto o status não virar connected e mostre uma mensagem clara quando a API responder 402 ou 403, para o usuário saber que o problema não é a câmera dele.