Como conectar um número de WhatsApp à API por QR code ou código de pareamento
Passo a passo para parear um número de WhatsApp na API: buscar o QR code, usar o código de 8 caracteres, acompanhar o status e o que muda depois de conectar.
Antes da primeira mensagem enviada pela API existe um passo que costuma gerar mais dúvida do que o próprio envio: conectar o número. Onde aparece o QR code? Ele expira? Dá para conectar sem câmera, direto pelo celular? O que acontece se o servidor reiniciar, ou se o celular ficar sem bateria?
A resposta curta é que conectar um número à apiwpp funciona igual a abrir o WhatsApp Web: você mostra um QR code, o dono do número escaneia em Aparelhos conectados e pronto. A diferença é que tudo acontece por HTTP, então o seu sistema pode exibir o QR code onde quiser, acompanhar o status em tempo real e oferecer um código de 8 caracteres para quem não consegue escanear.
Este tutorial mostra o caminho completo, com as chamadas reais da API: criar a conexão, buscar o QR code no ritmo certo, pedir o código de pareamento, interpretar cada status e entender o que muda depois que o número conecta.
O que é "conectar" um número à API
Na apiwpp, uma conexão é um número de WhatsApp dentro de um projeto seu. Tecnicamente, ela é um aparelho conectado do número, o mesmo mecanismo do WhatsApp Web e do WhatsApp para computador. A API usa o protocolo do WhatsApp Web; não é a API oficial da Meta, então não há aprovação de conta nem de modelos de mensagem.
Isso tem três consequências práticas:
- O número continua no celular. O dono segue usando o WhatsApp normalmente; a API é só mais um aparelho na lista de aparelhos conectados.
- O pareamento acontece uma vez. Depois de conectado, a sessão fica salva e criptografada nos servidores da apiwpp. Reinícios, atualizações e quedas de rede não pedem um QR code novo.
- O celular não precisa ficar ligado. Como todo aparelho conectado, a sessão da API funciona mesmo com o celular desligado ou sem internet.
Há dois jeitos de parear: escanear um QR code ou digitar um código de pareamento de 8 caracteres no celular. Os dois terminam no mesmo lugar, com a conexão no status open. Se você quer entender o recurso antes do passo a passo, a página de conexão por QR code ou código de pareamento resume o que ele faz.
Antes de começar: projeto, chave e escopos
Você precisa de três coisas:
- Uma conta na apiwpp. O teste de 7 dias inclui um número e os recursos PRO, sem cartão de crédito.
- Um projeto. O projeto (o
tenantda API) representa um sistema seu, com o próprio endereço de webhook e as próprias chaves. Anote oiddele. - Uma chave de API com os escopos certos. Crie no painel, em API keys. A chave (
wag_live_…) aparece uma única vez: guarde num cofre de segredos.
Os escopos importam mais do que parece no pareamento, porque escanear um QR code conecta um número à sua conta. Por isso só uma chave com connections:write recebe o QR code:
| Escopo | O que a chave consegue no pareamento |
|---|---|
connections:write | Criar a conexão, receber o QR code, pedir o código de pareamento, desconectar e fazer logout |
connections:read | Ver o status das conexões; o QR code vem null |
Na prática, a parte do seu sistema que mostra o QR code usa uma chave com os dois escopos, e um painel de monitoramento usa só connections:read: ele acompanha se os números estão conectados sem conseguir parear nada. Envie a chave em toda requisição, no cabeçalho Authorization: Bearer ou em X-Api-Key.
Passo 1: crie a conexão
A conexão é criada dentro do projeto. O externalId é opcional e serve para você guardar o identificador do seu lado, como o id do cliente no seu sistema:
curl -s -X POST https://api.apiwpp.com/connections \
-H "Authorization: Bearer $APIWPP_KEY" \
-H "Content-Type: application/json" \
-d '{"tenantId": "'"$TENANT_ID"'", "externalId": "loja-42"}'
{ "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f", "externalId": "loja-42" }
Guarde o connectionId: ele é o $ID de todas as chamadas seguintes. Uma conexão sem sessão começa a parear assim que é criada.
Cada conexão ocupa um dos números que a sua organização contratou, até ser excluída. Se todos já estiverem em uso, a resposta é 402 com "code": "number_limit_reached". Aumentar a quantidade de números libera a vaga na hora, com a diferença do mês cobrada de forma proporcional; os valores por número estão em preços.
Passo 2: pareie pelo QR code
Busque o QR code a cada 2 a 5 segundos
O QR code não é uma imagem fixa. O WhatsApp troca o código a cada poucos segundos, e um código antigo não pareia. Por isso o seu sistema consulta a API em intervalos curtos e mostra sempre o mais recente:
curl -s https://api.apiwpp.com/connections/$ID/qr \
-H "Authorization: Bearer $APIWPP_KEY"
{ "qr": "2@k8Jd0Qf3mX1pT7vZ9sLr4eYw6nHc2bGa,…", "status": "connecting" }
O campo qr é o conteúdo do QR code, não a imagem. Você gera a imagem com qualquer biblioteca de QR code. Se preferir a imagem pronta, a rota do projeto responde o QR code como data URL PNG, para usar direto numa tag de imagem:
curl -s https://api.apiwpp.com/tenants/$TENANT_ID/connections/$ID/qr \
-H "Authorization: Bearer $APIWPP_KEY"
{ "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…", "status": "connecting" }
As duas rotas trazem o status junto, então a mesma consulta serve para desenhar o QR code e para saber quando o pareamento terminou.
Um exemplo em Node.js
O script abaixo, em TypeScript com fetch e a biblioteca qrcode, consulta a rota a cada 3 segundos, desenha o QR code no terminal só quando ele muda e para quando a conexão abre. É um bom jeito de parear um número da sua própria empresa sem montar uma tela:
import QRCode from 'qrcode'
const API = 'https://api.apiwpp.com'
const headers = { Authorization: `Bearer ${process.env.APIWPP_KEY}` }
const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
type QrResponse = { qr: string | null; status: 'connecting' | 'open' | 'close' | 'passkey_required' }
export async function pairByQr(connectionId: string, timeoutMs = 3 * 60_000): Promise<string> {
const deadline = Date.now() + timeoutMs
let lastQr: string | null = null
let closedPolls = 0
while (Date.now() < deadline) {
const res = await fetch(`${API}/connections/${connectionId}/qr`, { headers })
if (!res.ok) throw new Error(`qr failed: ${res.status} ${await res.text()}`)
const { qr, status } = (await res.json()) as QrResponse
if (status === 'open') return 'open'
if (status === 'passkey_required') return status
// A close right after the scan is normal (restart_required); a lasting one is not.
closedPolls = status === 'close' ? closedPolls + 1 : 0
if (closedPolls >= 5) return 'close'
if (qr && qr !== lastQr) {
lastQr = qr
console.clear()
console.log(await QRCode.toString(qr, { type: 'terminal', small: true }))
console.log('WhatsApp > Aparelhos conectados > Conectar um aparelho')
}
await sleep(3000)
}
return 'timeout'
}
Num produto, a lógica é a mesma, dividida em duas partes: o seu backend consulta a API com a chave (que nunca vai para o navegador) e repassa só o QR code e o status; a tela consulta o seu backend a cada poucos segundos e troca a imagem. O guia sobre colocar o WhatsApp dentro do seu SaaS mostra essa tela com a rota de data URL.
Escaneie no celular
No celular do número, o dono abre WhatsApp › Aparelhos conectados › Conectar um aparelho e aponta a câmera para o QR code. Quando o pareamento termina, o status passa a open, o qr volta a null e o projeto recebe o webhook connection.status com o número pareado:
{
"type": "connection.status",
"connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
"tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
"externalId": "loja-42",
"timestamp": "2026-07-01T12:00:00.000Z",
"data": { "status": "open", "phoneNumber": "5511988887777" }
}
Se ninguém escanear a tempo, a conexão fecha com o motivo qr_not_scanned e espera uma nova tentativa. Para gerar QR codes de novo, chame POST /tenants/{id}/connections/{connId}/connect.
Passo 2, alternativa: o código de pareamento de 8 caracteres
Quem acessa o seu sistema pelo próprio celular não consegue escanear um QR code que está na mesma tela. Para esse caso existe o código de pareamento: o dono do número digita no celular um código de 8 caracteres, sem câmera.
O código só pode ser pedido enquanto a conexão está pareando com o QR code na tela, ou seja, depois que o qr aparece em GET /connections/{id}/qr. Peça o código informando o número que vai ser conectado, no formato internacional:
curl -s -X POST https://api.apiwpp.com/connections/$ID/pairing-code \
-H "Authorization: Bearer $APIWPP_KEY" \
-H "Content-Type: application/json" \
-d '{"phone": "+5511988887777"}'
{ "code": "K7QX2M9P", "phone": "+5511988887777", "expiresAt": 1782907365000 }
No celular, o caminho é WhatsApp › Aparelhos conectados › Conectar um aparelho › Conectar com número de telefone. O campo separa o código em dois grupos de 4 (K7QX-2M9P), e o celular também recebe um aviso do pedido. Depois é só esperar o open, como no QR code.
O código vale até expiresAt, em milissegundos desde 1970: é quando terminam os QR codes daquela tentativa, no máximo cerca de 2,5 minutos depois de o primeiro aparecer. Depois disso ele não conecta mais, e é preciso pedir outro. As respostas que a sua integração deve tratar:
| Resposta | Quando acontece | O que fazer |
|---|---|---|
200 | O código foi gerado | Mostrar o código e o prazo |
400 | phone não está no formato internacional | Corrigir o número, com país e DDD |
409 not_pairing | A conexão não está com o QR code na tela, ou faltam menos de 30 segundos para os QR codes acabarem | Conectar de novo; com Retry-After, pedir depois desse tempo |
409 already_paired | A conexão já está pareada com um número | Fazer logout para conectar outro número |
429 pairing_code_too_soon | Um código foi pedido há menos de 30 segundos, ou o número já recebeu 5 códigos na última hora | Esperar os segundos do Retry-After |
Os limites existem porque cada pedido gera um aviso no celular: uma conexão pode pedir um código a cada 30 segundos, e um mesmo número recebe no máximo 5 códigos por hora, qualquer que seja a conexão que pede.
Os status da conexão e o caso da passkey
Durante e depois do pareamento, o campo status diz em que pé a conexão está:
status | O que quer dizer | O que o seu sistema faz |
|---|---|---|
connecting | Abrindo a conexão ou esperando a leitura do QR code | Mostrar o QR code ou o código |
open | Pareada e conectada: pode enviar e receber | Liberar os envios |
close | Sem conexão ativa: desconectada, sessão encerrada ou pareamento interrompido | Ver o reason e conectar de novo se preciso |
passkey_required | O QR code foi lido, mas o WhatsApp pediu uma passkey ao celular | Avisar o usuário e tentar mais tarde |
Um cuidado honesto sobre o último caso. Desde meados de 2026, o WhatsApp pede a alguns celulares uma passkey (chave de acesso) logo depois da leitura do QR code, e a apiwpp ainda não consegue concluir essa etapa. Quando isso acontece, a API para de gerar QR codes, responde passkey_required e envia connection.status com "status": "close" e "reason": "passkey_required". O código de pareamento não evita a passkey.
A sessão fica guardada: dá para tentar de novo mais tarde com POST /tenants/{id}/connections/{connId}/connect, ou usar outro número. Números já pareados não são afetados, porque a passkey só aparece em pareamentos novos. Prever essa mensagem na sua tela evita que o usuário fique escaneando QR codes sem entender o que houve.
Depois de conectar: sessão, celular e os primeiros dias
Com o status open, o número está pronto para enviar mensagens pela API. Quatro coisas passam a valer a partir desse momento.
A sessão fica salva
A sessão é guardada criptografada nos servidores da apiwpp. Reinícios, atualizações e quedas de rede não pedem QR code novo: a conexão volta sozinha. Os detalhes estão em sessão persistente.
O celular pode ficar desligado
A API é um aparelho conectado, não um espelho do celular. O número continua enviando e recebendo pela API com o celular desligado, sem bateria ou sem internet. O que encerra a sessão é um logout, o dono remover o aparelho na lista de aparelhos conectados ou o próprio WhatsApp encerrar os aparelhos conectados (o evento connection.status chega com reason: logged_out); abrir o WhatsApp no celular de vez em quando evita isso.
Acompanhe o evento connection.status
Toda mudança da conexão chega pelo webhook connection.status. Um fechamento sempre traz o motivo (reason) e se a apiwpp vai reconectar sozinha (willReconnect):
reason | O que houve | Reconecta sozinha? |
|---|---|---|
transient | Queda de rede ou erro do lado do WhatsApp | Sim, com espera crescente |
restart_required | O WhatsApp pediu uma conexão nova, o que é normal logo depois do pareamento | Sim, na hora |
replaced | Outro cliente assumiu a sessão | Não: espera uma reconexão |
qr_not_scanned | Ninguém escaneou os QR codes de uma conexão nunca pareada | Não |
logged_out | A sessão acabou do lado do WhatsApp, por exemplo com o aparelho removido no celular | Não: precisa de um QR code novo |
manual | Você chamou POST /connections/{id}/disconnect | Não: espera uma reconexão |
Uma regra simples para alertas: avise alguém na hora quando chegar um fechamento com willReconnect: false, e num fechamento com true só se nenhum open chegar dentro do prazo que você definir. Como receber e validar esses eventos está no guia de webhooks do WhatsApp.
Começa o aquecimento de 14 dias
Um número recém-pareado envia mais devagar durante 14 dias e alcança poucas pessoas novas por dia: nas primeiras 6 horas, são até 5 envios por hora, 20 por dia e 5 destinatários novos. Os limites sobem por etapas até chegar ao ritmo normal. É nessa fase que o WhatsApp mais restringe quem começa conversas com desconhecidos, e o aquecimento reduz esse risco, sem garantir que o número nunca será restringido. As etapas completas e o que fazer em cada uma estão no guia sobre aquecimento de número.
Desconectar, reconectar e trocar de número
A diferença entre desconectar e fazer logout é a dúvida mais comum depois do pareamento, e errar aqui custa caro, porque um novo pareamento recomeça o aquecimento:
| Chamada | Efeito |
|---|---|
POST /connections/{id}/disconnect | Fecha a conexão e guarda a sessão: reconecte sem QR code |
POST /tenants/{id}/connections/{connId}/connect | Reconecta com a sessão guardada, ou começa um pareamento se não houver sessão |
POST /connections/{id}/logout | Sai do WhatsApp e apaga a sessão: o próximo pareamento pede QR code novo. Use para trocar o número |
DELETE /tenants/{id}/connections/{connId} | Sai do WhatsApp e exclui a conexão, com a sessão, os templates e o histórico. Não pode ser desfeito |
Três situações que confundem:
- "A conexão caiu, vou parear de novo." Não faça isso antes de olhar o
reason. Umtransientse resolve sozinho, e um novo pareamento zera o aquecimento e os contatos conhecidos do número. - "Quero trocar o número desta conexão." Faça logout e pareie o número novo na mesma conexão. Ele começa o próprio aquecimento.
- "A fatura atrasou e os números caíram." Depois dos 5 dias de tolerância, a conta é suspensa e os números são desconectados com a sessão guardada. Com o pagamento confirmado, eles voltam sem QR code novo.
Como começar hoje
- Crie um projeto e uma chave de API com
connections:readeconnections:writepara a parte do sistema que faz o pareamento. - Crie a conexão com
POST /connections, informando otenantIde, se quiser, oexternalIddo seu cliente. - Consulte o QR code a cada 2 a 5 segundos e mostre sempre o mais recente, ou ofereça o código de 8 caracteres para quem está no celular.
- Configure o webhook do projeto e trate o
connection.status: libere os envios noopene alerte nos fechamentos comwillReconnect: false. - Planeje os primeiros 14 dias do número com o aquecimento em mente e evite pareamentos desnecessários.
- Crie sua conta na apiwpp e conecte o primeiro número no teste de 7 dias.
Perguntas frequentes
De quanto em quanto tempo devo buscar o QR code?
A cada 2 a 5 segundos. O WhatsApp troca o QR code a cada poucos segundos e um código antigo não pareia, então a sua tela deve mostrar sempre o mais recente. A mesma consulta traz o status, que avisa quando a conexão abriu.
Por que o QR code vem null na resposta?
Há três motivos comuns. A chave pode ter só o escopo connections:read, e o QR code só é entregue a quem tem connections:write. A conexão pode já estar open, sem QR code para escanear. Ou ela pode estar fechada, e aí é preciso chamar a rota de conectar de novo.
Qual a diferença entre o QR code e o código de pareamento?
Os dois conectam o número do mesmo jeito. O QR code precisa de uma câmera apontada para outra tela; o código de 8 caracteres é digitado no próprio celular, em "Conectar com número de telefone". O código é a melhor opção para quem acessa o seu sistema pelo celular.
O celular precisa ficar ligado depois de conectar?
Não. A API funciona como um aparelho conectado, igual ao WhatsApp Web, e a sessão fica salva nos servidores da apiwpp. O número continua enviando e recebendo com o celular desligado. A sessão termina com um logout, se o aparelho for removido no celular ou se o próprio WhatsApp encerrar os aparelhos conectados por falta de uso do celular.
Reiniciar o servidor ou desconectar pede um QR code novo?
Não. Reinícios, atualizações, quedas de rede e a desconexão pela API mantêm a sessão guardada, e a conexão volta sem QR code. Só o logout, a exclusão da conexão ou a remoção do aparelho no celular exigem um novo pareamento, que também recomeça o aquecimento.
O que fazer quando a conexão para com passkey_required?
Isso acontece quando o WhatsApp pede uma passkey ao celular logo depois da leitura, etapa que a apiwpp ainda não conclui. A sessão fica guardada: tente conectar de novo mais tarde ou use outro número. Números já pareados não são afetados.
Leia também: