API de WhatsApp com QR Code: como conectar um número

Como o pareamento por QR funciona

Quando você cria uma sessão na API de WhatsApp, ela nasce desconectada, esperando um aparelho. O QR carrega o convite para o celular vincular aquela sessão como um dispositivo, do mesmo jeito que acontece ao abrir o WhatsApp Web. Depois da leitura, o número continua funcionando no celular e a sessão passa a ter acesso às conversas.

Na D-API, o ciclo tem quatro momentos:

1. Criar a sessão com um sessionId seu.
2. Buscar o QR e exibir para quem vai conectar.
3. Acompanhar a mudança de status até connected.
4. Tratar desconexões ao longo do tempo, reconectando ou pedindo um novo pareamento.

Gerar o QR pela API

A rota é GET /api/v1/sessions/{sessionId}/qr. Com ?image=1, a resposta é um PNG pronto para exibir ou salvar:

curl "https://api.d-api.cloud/api/v1/sessions/clinica-norte/qr?image=1" \
  -H "Authorization: SUA_API_KEY" \
  --output qr.png

Sem o parâmetro, a resposta vem em JSON, útil quando o seu frontend vai desenhar a imagem:

{
  "sessionId": "clinica-norte",
  "status": "connecting",
  "qrCode": "2@ABC123DEF456...",
  "qrCodeImage": "data:image/png;base64,iVBOR...",
  "qrCodeUpdatedAt": "2024-01-15T10:30:00.000Z"
}

O campo qrCodeImage já vem como data URL e pode ir direto no atributo src de uma imagem. O qrCodeUpdatedAt ajuda a saber se o QR na tela ainda é o atual.

Expiração e renovação do QR

O QR expira em segundos e é renovado automaticamente enquanto a sessão está em connecting. Se a tela mostrar sempre o primeiro QR gerado, a leitura vai falhar. Há duas formas de manter a imagem atualizada:

• Buscar em intervalo curto enquanto o status for connecting, e parar assim que mudar. É o caminho mais simples para uma primeira versão.
• Reagir aos webhooks. O evento connection.qrcode avisa que há um QR novo, e o connection.status avisa quando o número conectou. Com isso, seu backend empurra a atualização para a tela sem ficar consultando.

Um detalhe de segurança: a chamada que busca o QR deve sair do seu backend. A API Key dá acesso a todas as sessões da conta e não deve ir para o navegador do seu cliente.

Pareamento por código, sem câmera

Nem sempre dá para escanear. Se a pessoa está vendo a sua tela no próprio celular, não há como apontar a câmera para ele mesmo. Para isso existe o código de pareamento: você cria a sessão com connectionMode igual a pair e informa o número em pairPhone.

curl -X POST https://api.d-api.cloud/api/v1/sessions \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sessionId": "clinica-norte", "connectionMode": "pair", "pairPhone": "5511999999999" }'

curl https://api.d-api.cloud/api/v1/sessions/clinica-norte/pair-code \
  -H "Authorization: SUA_API_KEY"

A resposta traz o pairCode, no formato ABCD-1234, que a pessoa digita no celular na opção de conectar com número de telefone. Quando o código muda, o evento connection.paircode chega no webhook. No SDK de Node, os equivalentes são sessions.getQRCode e sessions.getPairCode; veja o SDK de Node.js.

Migrar um WhatsApp Web já conectado

Quando o número já está aberto no WhatsApp Web de alguém, por exemplo de uma atendente que usa o navegador todo dia, dá para levar essa sessão para a D-API sem novo QR. O caminho usa o Assistente de Integração, uma extensão do Chrome:

1. Seu sistema gera um código de migração com POST /api/v1/sessions/{sessionId}/migration-otp. O código tem 8 caracteres, vale por 30 minutos e só pode ser usado uma vez.
2. A pessoa instala o Assistente de Integração no Chrome em que o WhatsApp Web está aberto.
3. Ela informa o código na extensão, que transfere a sessão para a D-API.
4. O WhatsApp Web daquele navegador é desconectado e o número passa a operar pela API.

Esse código não é um código de verificação para usuário final; ele existe só para essa migração. É um recurso útil para quem está trazendo clientes de outro fornecedor ou de uma operação manual, sem pedir que cada um repita o pareamento.

Reconexão e quando pedir um QR novo

Depois de conectado, o número pode cair por motivos diferentes, e cada um pede uma reação diferente do seu sistema. O webhook connection.status traz o estado em data.status:

O que diferencia uma boa integração é o cliente saber da queda pela sua tela, e não por ter parado de receber mensagem. Se você vai conectar números de vários clientes, veja como organizar isso em múltiplos números na mesma API, e o fluxo completo, do cadastro ao webhook, em como funciona a API de WhatsApp. A conexão por QR é a base da API não oficial da D-API.