conexão por código
Código de pareamento WhatsApp API para conectar o número só com o celular
Com o código de pareamento WhatsApp API da D-API, o seu cliente conecta o número digitando um código de 8 caracteres no próprio celular. Serve para quem configura o seu SaaS pelo telefone e não tem outra tela para escanear um QR code.
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
Sem câmera, sem segunda tela
O cliente informa o número, o seu produto mostra o código e ele digita no WhatsApp. Tudo acontece no mesmo aparelho.
Código pela API ou por webhook
Busque em GET /sessions/{sessionId}/pair-code ou receba no evento connection.paircode, com o código e o telefone.
Mesma sessão, mesmos recursos
Depois de conectado pelo código, o número funciona igual a uma conexão por QR code: mensagens, grupos, ligações e webhooks.
O código de pareamento WhatsApp API é a alternativa ao QR code para conectar um número. Em vez de apontar a câmera para uma tela, o dono do número digita no WhatsApp um código de 8 caracteres que o seu produto exibe. Parece detalhe, e na prática resolve o onboarding de uma fatia grande de clientes de SaaS: o dono do restaurante que configura o sistema de delivery pelo celular, o corretor que só usa o telefone, a dona da clínica que está fora do consultório quando decide ativar o WhatsApp.
O pareamento por código faz parte da API não oficial da D-API e gera a mesma sessão de uma conexão por QR. A diferença está só no primeiro minuto.
Quando o código de pareamento é melhor que o QR code
O QR code pressupõe duas telas: a do computador, que mostra o código, e a do celular, que escaneia. Sempre que essa condição falha, o código de pareamento salva a conexão.
Cliente que usa o seu SaaS pelo celular. Se o seu painel é responsivo e boa parte dos clientes acessa pelo telefone, o QR aparece no mesmo aparelho que deveria escaneá-lo. Com o código, o cliente copia, troca de app e digita.
Suporte remoto. O seu time de onboarding está numa chamada com o cliente e pode ditar o código, ou mandar por mensagem, sem pedir que ele compartilhe a tela.
Câmera ruim ou leitura falhando. Celular antigo, tela com reflexo, monitor com brilho baixo. O código digitado não depende de nada disso.
Para a maioria dos clientes de desktop, o QR continua sendo o caminho mais rápido. Por isso vale oferecer as duas opções na tela de conexão e deixar o cliente escolher.
Como ativar o código de pareamento pela API
O modo de pareamento é definido na criação da sessão. Use connectionMode: "pair" e informe o número em pairPhone, com código do país e só dígitos. Sem o número, o pareamento por código não tem como ser gerado.
curl -X POST https://api.d-api.cloud/api/v1/sessions \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "delivery-pizzaria-centro",
"type": "unofficial",
"connectionMode": "pair",
"pairPhone": "5511999999999",
"webhookUrl": "https://seu-saas.com/webhooks/whatsapp"
}'
A D-API sobe a conexão e pede o código ao WhatsApp para aquele número. O código fica disponível em segundos, por dois caminhos.
Buscar o código na rota de pareamento
curl https://api.d-api.cloud/api/v1/sessions/delivery-pizzaria-centro/pair-code \
-H "Authorization: SUA_API_KEY"
{
"sessionId": "delivery-pizzaria-centro",
"status": "connecting",
"pairCode": "ABCD-1234",
"pairPhone": "5511999999999",
"pairCodeUpdatedAt": "2024-01-15T10:30:00.000Z",
"connectionMode": "pair"
}
Enquanto o código ainda não foi gerado, a rota responde 404 com "Pair code not available". Trate essa resposta como “aguardando” e consulte de novo em poucos segundos, exibindo um indicador de carregamento na tela. O pairPhone da resposta é útil para mostrar ao cliente para qual número o código vale, o que evita que ele digite o código no celular errado.
Receber o código por webhook
Se a sua arquitetura já é orientada a eventos, o código chega sozinho no evento connection.paircode:
{
"event": "connection.paircode",
"sessionId": "delivery-pizzaria-centro",
"timestamp": "2026-01-24T22:00:05.000Z",
"data": {
"code": "ABCD-1234",
"phone": "5511999999999"
}
}
O seu backend recebe, identifica o tenant pelo sessionId e empurra o código para a tela do cliente. A mesma infraestrutura de webhook que você monta aqui vai servir para mensagens, status e ligações depois. O artigo sobre webhooks da API de WhatsApp cobre retentativas e deduplicação.
O que o cliente faz no celular
O texto de instrução ao lado do código decide se o cliente conecta sozinho ou abre chamado. O caminho no WhatsApp é este:
- Abrir o WhatsApp no celular do número informado.
- Ir em Configurações e depois em Aparelhos conectados.
- Tocar em Conectar um aparelho.
- Escolher a opção Conectar com número de telefone.
- Digitar o código mostrado no seu produto.
Depois da confirmação, a conexão aparece na lista de aparelhos do cliente como um navegador Chrome em Linux, igual a uma sessão de WhatsApp Web. Vale avisar isso na tela, para o cliente não estranhar quando abrir a lista e encontrar o dispositivo.
Inclua um botão de copiar ao lado do código. Quem está no celular vai precisar trocar de aplicativo, e decorar oito caracteres no caminho é pedir erro.
Confirmar a conexão e seguir com o onboarding
A confirmação chega pelo mesmo evento de qualquer conexão: connection.status com status: "connected", o número, o nome exibido na conta e o JID. Com ele, o seu produto encerra a etapa de conexão e passa para o próximo passo do onboarding, que pode ser importar contatos, configurar mensagens automáticas ou ativar o lembrete de consulta.
Compare o phone recebido com o pairPhone informado. Se forem diferentes, alguém conectou outro número, e o melhor é avisar antes que o cliente comece a usar.
O ciclo de vida segue o padrão da conexão não oficial. Se o cliente remover o aparelho no celular, chega connection.status com logged_out, e a reconexão exige um código novo. E se a sessão tiver entrado em espera, sinalizada pelo status qrcode_timeout, um novo pedido à rota de código de pareamento também acorda a sessão.
A descrição completa dos eventos de conexão está na documentação da D-API.
Código de pareamento num SaaS com muitos clientes
Para quem conecta dezenas ou centenas de números, três cuidados mantêm o fluxo previsível.
Valide o telefone antes de criar a sessão. Remova espaços, parênteses e o sinal de mais, e confira se o código do país está presente. Um número mal formatado gera uma sessão que nunca recebe código.
Use um sessionId que carregue o identificador do cliente, como delivery-pizzaria-centro. O webhook de pareamento e o de conexão chegam com esse identificador, e o roteamento para a tela certa fica direto.
Mostre o estado da conexão no painel do seu cliente o tempo todo, não só no onboarding. “Conectado”, “aguardando código” e “precisa reconectar” são três estados que o cliente entende, e cada um corresponde a um evento que a D-API já envia. A visão geral da plataforma está na página da API de WhatsApp.
Time D-API. Atualizado em .
Perguntas frequentes
Qual formato o número em pairPhone precisa ter?
Código do país mais DDD e número, só com dígitos, sem espaço, parênteses ou sinal de mais. Para um celular de São Paulo, algo como 5511999999999.
Como a conexão aparece no celular do cliente?
Na lista de Aparelhos conectados do WhatsApp, como um navegador Chrome em Linux, do mesmo jeito que uma sessão de WhatsApp Web.
Posso oferecer QR code e código de pareamento na mesma tela?
Pode, mas cada sessão é criada em um modo. Pergunte ao cliente como ele prefere conectar antes de chamar POST /api/v1/sessions e use connectionMode qr ou pair conforme a resposta.
O código de pareamento serve para a API Oficial?
Não. Conexões Cloud API são criadas pela conta da Meta do cliente, e a rota de código de pareamento responde 409 para elas.