Pular para o conteúdo
D-APITestar grátis

conexão por qr code

API WhatsApp QR code para conectar o número do cliente dentro do seu produto

Com a API WhatsApp QR code da D-API, o seu SaaS busca o código de conexão, mostra na própria tela com a sua marca e recebe um webhook no instante em que o cliente escaneia. Ninguém precisa entrar num painel de terceiros.

SaaS testa 14 dias com o time técnico ajudando na integração.

conexões na D-API
1.875
de uptime garantido em contrato
99,9%
datacenters no Brasil
4
por ligação de WhatsApp na API não-oficial
R$ 0
  • JSON, PNG ou webhook

    Busque o QR como texto e imagem base64, peça o PNG direto com ?image=1 ou receba cada código novo pelo evento connection.qrcode.

  • Renovação automática

    O código é renovado sozinho enquanto o número não conecta. Uma consulta nova sempre traz o QR válido, e o expirado vem sinalizado.

  • Aviso de conexão em tempo real

    Quando o cliente escaneia, chega connection.status com status connected, número, nome e JID da conta.

A API WhatsApp QR code resolve o primeiro atrito de qualquer SaaS que oferece WhatsApp: fazer o cliente conectar o número. Em vez de mandar o cliente para um painel externo, o seu produto busca o código pela API, exibe na tela de configurações com a sua identidade visual e fica sabendo, por webhook, no momento em que o número conectou. Para o dono da clínica ou o gerente da loja, é um passo a mais no onboarding do seu sistema, e nada além disso.

O QR é o pareamento da API não oficial: o mesmo mecanismo do WhatsApp Web, em que o celular autoriza um novo aparelho conectado. Na D-API, esse aparelho é a sessão que o seu sistema controla.

Como buscar o QR code pela API

Depois de criar a sessão com POST /api/v1/sessions (o modo padrão já é connectionMode: "qr"), o código fica disponível em uma rota de leitura.

curl https://api.d-api.cloud/api/v1/sessions/agenda-pro-cliente-42/qr \
  -H "Authorization: SUA_API_KEY"
{
  "sessionId": "agenda-pro-cliente-42",
  "status": "connecting",
  "qrCode": "2@ABC123DEF456...",
  "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "qrCodeUpdatedAt": "2024-01-15T10:30:00.000Z"
}

O qrCodeImage é uma data URL pronta para ir num <img src>. Se o seu front-end prefere desenhar o código com uma biblioteca própria, use o texto em qrCode. E quando o objetivo é só abrir a imagem, acrescente ?image=1: a resposta vem como PNG binário, com Cache-Control: no-cache.

A imagem é sempre gerada a partir do código mais recente daquela leitura. Na prática, isso elimina uma classe chata de bug em que a tela mostra um QR antigo enquanto o texto já mudou.

Polling ou webhook: como manter o QR atualizado

O QR do WhatsApp é renovado a cada poucos segundos enquanto ninguém escaneia. O seu produto precisa mostrar sempre o atual, e há dois jeitos de fazer isso.

Polling na rota de QR. A tela de conexão consulta GET /api/v1/sessions/{sessionId}/qr em intervalo curto e troca a imagem quando qrCodeUpdatedAt muda. Um código com mais de um minuto vem marcado com expired: true, qrCode: null e uma imagem de “QR expirado”, que você pode mostrar enquanto a próxima consulta traz o novo. É o caminho mais simples para um front-end que conversa com o seu backend.

Webhook connection.qrcode. Cada código novo chega ao seu endpoint com o texto em qr e a imagem em qrImage. Códigos idênticos ao anterior são deduplicados e não geram evento.

{
  "event": "connection.qrcode",
  "sessionId": "agenda-pro-cliente-42",
  "timestamp": "2026-01-24T22:00:00.000Z",
  "data": {
    "qr": "2@abc...",
    "qrImage": "data:image/png;base64,iVBOR..."
  }
}

O qrImage pode vir null se a geração da imagem falhar; nesse caso, renderize a partir de qr. Com o webhook, o seu backend empurra o código para o navegador por WebSocket ou server-sent events, sem polling na D-API. Os detalhes de entrega e retentativa estão no artigo sobre webhooks da API de WhatsApp.

Saber a hora exata em que o número conectou

O momento que importa para o seu produto é a troca de “aguardando leitura” para “conectado”. Ele chega pelo evento connection.status:

{
  "event": "connection.status",
  "sessionId": "agenda-pro-cliente-42",
  "timestamp": "2026-01-24T22:00:30.000Z",
  "data": {
    "status": "connected",
    "jid": "[email protected]",
    "phone": "558005915338",
    "name": "Minha Empresa",
    "connected": true
  }
}

Com esse evento, a tela de onboarding fecha o modal, mostra o número conectado e libera os recursos de WhatsApp para aquele cliente. Guarde o phone junto do tenant: ele confirma que o cliente conectou o número que disse que conectaria, e evita surpresas quando alguém escaneia com o celular errado.

O mesmo evento avisa quando a conexão precisa de atenção. logged_out indica que o aparelho foi removido no celular, e o caminho é gerar um QR novo. disconnected traz o motivo em reason.

Quando ninguém escaneia: o qrcode_timeout

Um cenário comum em SaaS: o cliente abre a tela de conexão, é chamado para outra coisa e esquece a aba aberta, ou fecha sem escanear. Para não manter um processo gerando códigos para sempre, a D-API coloca em espera a sessão que passa 45 minutos gerando QR sem leitura e sem nenhum pedido de QR nesse período. Você recebe um único connection.status com status: "qrcode_timeout", e os eventos connection.qrcode param.

Nada é apagado. A sessão, as configurações e o webhook continuam os mesmos, e a próxima consulta à rota de QR acorda a sessão. Essa primeira resposta vem com o QR anterior marcado como expirado; o novo aparece em alguns segundos. Cada pedido de QR também zera a contagem, então uma tela que consulta o código enquanto está aberta nunca entra em espera.

Se o seu front-end mostra o QR só a partir do webhook, trate o qrcode_timeout chamando a rota de QR quando o cliente voltar à tela de conexão.

Boas práticas de UX para o QR no seu SaaS

Alguns detalhes separam um onboarding que converte de um que gera chamado no suporte.

Mostre as instruções ao lado do código, na língua do seu cliente: abrir o WhatsApp no celular, ir em Aparelhos conectados, tocar em Conectar um aparelho e apontar a câmera. Parece óbvio para quem desenvolve, e não é para a recepcionista que nunca usou o WhatsApp Web.

Ofereça a alternativa do código de pareamento quando o cliente estiver no próprio celular, sem uma segunda tela para escanear. É o caso clássico do dono de restaurante configurando o sistema pelo telefone.

Para quem conecta muitos números, como uma operação com vários atendentes, monte o sessionId com o identificador do cliente e do número. Assim, o webhook de conexão já diz qual card atualizar. A página sobre vários números na mesma conta trata desse modelo.

E quando quem vai escanear não tem acesso ao seu produto, o painel da D-API gera um link público do QR code que vale por 30 minutos, que pode ser enviado para o dono do celular.

Por fim, trate a rota de QR como exclusiva da conexão não oficial. Sessões da API Oficial respondem 409 nessa rota, então, se o seu produto oferece os dois tipos, decida a tela de onboarding pelo tipo da conexão antes de pedir o código. A visão completa dos dois modelos está na página da API de WhatsApp.

A referência da rota, com todos os códigos de resposta, está na documentação da D-API.

Time D-API. Atualizado em .

Perguntas frequentes

Onde o meu cliente escaneia o QR code?

No WhatsApp do celular, em Aparelhos conectados, opção Conectar um aparelho. É o mesmo caminho usado para entrar no WhatsApp Web.

Consigo mostrar o QR com a minha marca, sem aparecer D-API?

Sim. A API devolve o conteúdo do QR e a imagem pronta. O seu front-end decide como exibir, com o seu layout e o seu texto de instrução.

O que acontece se o cliente fechar a tela sem escanear?

A sessão continua gerando códigos por um tempo. Depois de 45 minutos sem leitura e sem consultas, ela entra em espera e avisa com qrcode_timeout. Quando o cliente voltar, a próxima consulta ao QR acorda a sessão.

Dá para conectar sem QR code?

Dá. Crie a sessão com connectionMode pair e o número em pairPhone. O cliente digita um código de 8 caracteres no celular em vez de escanear.

Consigo buscar o QR pelo SDK de Node.js?

Sim. No d-api-sdk, dapi.sessions.getQRCode(sessionId) devolve o QR com a imagem em base64 no campo qrCodeImage.

A gente também é SaaS

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time técnico da D-API acompanha a integração no seu produto.

Continue por aqui

Liberar seu teste grátis

Responda rapidinho e o time libera seu teste pelo WhatsApp, com o time técnico ajudando na integração.

Seus dados são usados só pra liberar o teste. Sem spam.