QR code e status
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.
Parâmetros de caminho
idstring · uuidobrigatórioIdentificador da conexão (o número).
Respostas
| Código | Erro e descrição |
|---|---|
| 200 | qr: 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. |
| 400 | FST_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. |
| 401 | Sem chave de API, ou com uma chave desconhecida, revogada ou expirada. O corpo é {"error": "Unauthorized"}. |
| 402 | subscription_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. |
| 403 | A chave não tem o escopo connections:read; a mensagem de erro cita o escopo que falta. |
| 404 | A 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). |
| 429 | Requisições demais deste IP de origem, ou autenticações com falha demais: espere os segundos de Retry-After.Cabeçalho: Retry-After |
| 503 | A 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