Pular para o conteúdo

QR code e status

GET/connections/{id}/qr

O QR code atual (quando há um) e o status da conexão. Escanear o QR code pelo WhatsApp do celular (Aparelhos conectados › Conectar um aparelho) conecta o número à conexão. Escopo necessário: connections:read.

Ver em Markdown

Parâmetros de caminho

idstring · uuidobrigatório

Identificador da conexão (o número).

Respostas

Respostas: código de status, erro e descrição
CódigoErro e descrição
200qr: o texto do QR code a desenhar (por exemplo, com uma biblioteca de QR code), ou null quando não há um ou quando a chave não tem connections:write. status: connecting, open, close ou passkey_required.
400FST_ERR_VALIDATIONA requisição não segue o schema da operação (por exemplo, um id que não é um UUID); message diz o que está errado.
401Sem chave de API, ou com uma chave desconhecida, revogada ou expirada. O corpo é {"error": "Unauthorized"}.
402subscription_inactiveA organização dona da conexão não pode usar o WhatsApp agora: o período de teste acabou, ou uma fatura venceu e passou do prazo de carência. Pague para voltar a usar.
403A chave não tem o escopo connections:read; a mensagem de erro cita o escopo que falta.
404A conexão não existe ou não é de quem chama: a de outra pessoa responde exatamente como uma que não existe (Connection not found).
429Requisições demais deste IP de origem, ou autenticações com falha demais: espere os segundos de Retry-After.Cabeçalho: Retry-After
503A instância do gateway que roda a conexão está mudando (um reinício, um failover) ou não responde: espere os segundos de Retry-After e tente de novo.Cabeçalho: Retry-After

Detalhes

O QR code só aparece para quem tem o escopo connections:write: escaneá-lo conecta um número à conexão, como faz POST /connections/{id}/pairing-code. Só com connections:read, qr vem null e o status continua disponível.

O WhatsApp troca o QR code a cada poucos segundos enquanto a conexão pareia: consulte a cada 2 a 5 segundos e mostre sempre o último, porque um código antigo não pareia. Quando os QR codes de uma tentativa acabam sem leitura, a conexão fecha (connection.status com reason: qr_not_scanned); conecte-a de novo para mostrar QR codes novos.

status: passkey_required: o QR code foi escaneado, mas o pareamento não terminou porque o WhatsApp pediu uma passkey (chave de acesso) ao celular, o que este gateway ainda não consegue concluir. A conexão fica parada, sem QR codes novos, até ser conectada de novo, inclusive depois de reinícios (o status é gravado); o número pode ser pareado mais tarde, ou outro número pode ser usado. Veja Parear um número.

Uma conexão que não está rodando (depois de um logout, de QR codes expirados ou de POST /connections/{id}/disconnect) responde qr: null e status: close.

Guia: Parear um número

Esta página ajudou? · Atualizado em 28 set 2026