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

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:

  1. Abrir o WhatsApp no celular do número informado.
  2. Ir em Configurações e depois em Aparelhos conectados.
  3. Tocar em Conectar um aparelho.
  4. Escolher a opção Conectar com número de telefone.
  5. 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.

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.