Código de pareamento e QR

O QR muda a cada 20 segundos. Ofereça os dois caminhos, porque um onboarding feito em um único dispositivo não consegue fotografar a própria tela.

O pareamento se aplica às conexões qr. Um número cloud_api nunca escaneia nada e responde 409 not_supported_for_provider.

O caminho do QR

POST /connections retorna um QR inicial como PNG em data-URI.

Renderize o QR novamente a cada consulta

O WhatsApp troca o código de pareamento a cada 20 segundos, aproximadamente. O qr da resposta de criação fica desatualizado poucos segundos depois de ser exibido, e isso falha em silêncio: o celular nunca pareia e nada na tela explica o motivo.

Consulte GET /connections/{id} a cada 3–5 s e renderize novamente o qr de cada resposta até que status seja "connected". Não o guarde em cache e não esconda a atualização atrás de um botão que o usuário precise apertar.

A mesma regra vale para um replay idempotente: quando POST /connections retorna 200 com Idempotency-Replayed: true, o qr dessa resposta foi buscado de novo, e não reaproveitado do armazenamento — justamente porque um código guardado já não seria mais lido.

O caminho do código de pareamento

Um QR precisa de dois dispositivos: uma tela que o exiba e um celular que o fotografe. Boa parte dos onboardings reais acontece em um só dispositivo — o cliente conclui o seu fluxo no mesmo celular em que roda o WhatsApp e não consegue fotografar a própria tela. Para ele, o caminho do QR não é apenas incômodo: é impossível.

POST /connections/{id}/pairing-code

curl -X POST https://developers.wasync.app/api/v1/connections/conn_8f3a21/pairing-code \
  -H "Authorization: Bearer $WASYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"40740267964"}'

200 response

{
  "code": "7S59-1KZP"
}

O cliente abre o WhatsApp → Configurações → Aparelhos conectados → Conectar com número de telefone e digita o código.

phoneNumber está no formato E.164 sem o + inicial — somente dígitos. Qualquer outro formato é rejeitado com 400 { "error": "invalid_phone_number" } em vez de ser corrigido por nós: reescrever em silêncio o número enviado é o caminho para o cliente parear uma conta que ninguém pediu. Usa whatsapp.manage, o mesmo escopo da criação da conexão.

Nem sempre há um código de pareamento disponível — mantenha o QR como alternativa

O motor pode se recusar a emitir um. É um resultado comum, não uma falha do serviço, e a resposta é 502 { "error": "pairing_code_unavailable" } em vez de um 500 genérico, justamente para que você distinga os dois casos e leve o usuário de volta ao QR. Uma integração que ofereça apenas o caminho do código de pareamento, cedo ou tarde, mostrará ao cliente uma tela sem saída. Renderize os dois, lado a lado.

Pedir outro código

Você pode pedir outro código na mesma conexão: ele retorna um código novo e não recria a sessão, então um botão "enviar outro código" é seguro.

O limite é de 5 por conexão a cada 15 minutos; acima disso você recebe 429 { "error": "rate_limited" } com um cabeçalho Retry-After que deve ser respeitado. O limite não é burocracia — pedir códigos repetidamente para um mesmo número é exatamente o que os sistemas antiabuso do WhatsApp monitoram, e o número em risco é o do seu cliente.

Nada extra é consumido

O pareamento por código usa a mesma vaga paga e inicia o mesmo teste gratuito de 7 dias que a leitura de um QR: a licença é reservada quando o número realmente pareia, seja qual for o caminho usado.

O acompanhamento do sucesso também não muda. Não existe um evento "código aceito", então consulte GET /connections/{id} até que status seja "connected" e/ou escute o webhook connection.connected.

Duas recusas merecem tratamento no seu código:

409 already_connected — a sessão já está ativa, não há nada a parear.
409 not_supported_for_provider — um número cloud_api. Códigos de pareamento são um conceito de qr e nunca se aplicam aqui, então não tente de novo.

Parear de novo mais tarde

Uma sessão qr pode cair por conta própria. connection.disconnected avisa, e needs_reconnect é o campo que deve orientar a sua interface. O QR propositalmente não vem nesse payload — é uma credencial de login por leitura —, então busque-o em GET /connections/{id} e mostre-o ao dono do número exatamente como na configuração inicial. Veja Webhooks.

Esta página foi útil?