--- title: "API de WhatsApp com QR Code: conectar números | D-API" description: "Conecte números pela API de WhatsApp com QR Code: gere o QR em PNG ou JSON, use código de pareamento, migre um WhatsApp Web ativo e trate a reconexão." url: https://d-api.cloud/api-whatsapp-qr-code --- Guia da API de WhatsApp # API de WhatsApp com QR Code: como conectar um número Na API de WhatsApp não oficial, o número é conectado como no WhatsApp Web: a API gera um QR, o dono escaneia pelo celular e a sessão passa a enviar e receber. Também dá para parear por código, sem câmera, ou migrar um WhatsApp Web já aberto. Por Time de engenharia D-APIAtualizado em 24 de set de 20265 min de leitura ## Como o pareamento por QR funciona Quando você cria uma sessão na [API de WhatsApp](https://d-api.cloud/), 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](https://d-api.cloud/integrations/nodejs-sdk). ## 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`: | Status | O que significa | O que fazer | | --- | --- | --- | | `connected` | Sessão ativa | Liberar envios para aquele número | | `disconnected` | Conexão perdida, pareamento mantido | Aguardar a reconexão automática ou forçar com `GET /sessions/{id}/connect` | | `logged_out` | Número desvinculado | Avisar o cliente e exibir um QR novo | 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](https://d-api.cloud/api-whatsapp-multiplos-numeros), e o fluxo completo, do cadastro ao webhook, em [como funciona a API de WhatsApp](https://d-api.cloud/como-funciona-api-de-whatsapp). A conexão por QR é a base da [API não oficial da D-API](https://d-api.cloud/api-nao-oficial-de-whatsapp). ## Perguntas frequentes ### Quanto tempo o QR code da API fica válido? Poucos segundos. O WhatsApp renova o QR continuamente enquanto a sessão aguarda pareamento, e a API acompanha essa renovação. Por isso a sua tela deve buscar o QR de novo em intervalos curtos, ou reagir ao evento de webhook de QR atualizado. ### Qual a diferença entre QR code e código de pareamento? No QR, a pessoa aponta a câmera do celular para a tela. No código de pareamento, ela digita no celular um código curto gerado para o número informado. O código é útil quando quem conecta está usando o próprio celular para ver a tela, e não tem como escanear. ### Preciso ler o QR de novo toda vez que a conexão cai? Não. Quedas por instabilidade são tratadas com reconexão, sem novo pareamento. Só é preciso um QR novo quando o número foi desvinculado, por exemplo quando o dono remove o aparelho vinculado no celular, o que chega como status logged\_out. ### Posso mostrar o QR dentro do meu próprio sistema? Sim, e é o uso mais comum. Seu backend busca o QR na API e entrega a imagem para o frontend, sem expor a API Key. O cliente final conecta o número sem sair do seu produto e sem saber que existe um fornecedor por trás. ### O que é o Assistente de Integração? É uma extensão do Chrome que migra para a D-API um WhatsApp Web que já está conectado no navegador, usando um código de 8 caracteres gerado pela API, sem ler QR. Depois da migração, o WhatsApp Web daquele navegador é desconectado. Teste a API de WhatsApp da D-API3 dias grátis, sem cartão.[Começar trial grátis](https://app.d-api.cloud/register) ## Continue lendo - [Guia da API de WhatsAppMúltiplos números no WhatsApp](https://d-api.cloud/api-whatsapp-multiplos-numeros) - [Guia da API de WhatsAppWebhook de WhatsApp](https://d-api.cloud/webhook-api-whatsapp) - [Guia da API de WhatsAppEnviar imagem, áudio e documento](https://d-api.cloud/api-whatsapp-enviar-midia) - [Guia da API de WhatsAppBotões e listas no WhatsApp](https://d-api.cloud/api-whatsapp-botoes-e-listas) ## Teste a API de WhatsApp da D-API Trial de 3 dias com acesso completo. Sem cartão, sem fidelidade. [Começar trial grátis](https://app.d-api.cloud/register)[Ver documentação](https://docs.d-api.cloud/)