--- title: "Conectar WhatsApp na API sem QR Code" description: "Três jeitos de conectar um número na API não oficial do WhatsApp: QR Code, código de pareamento de 8 caracteres e WAME Passkey. Com cURL, webhooks e reconexão." url: "https://api-wa.me/blog/conectar-whatsapp-codigo-pareamento-sem-qr-code" language: "pt-BR" og:type: "article" og:site_name: "WAME API" --- [Início](https://api-wa.me/)/[Blog da API do WhatsApp](https://api-wa.me/blog)/Conectar WhatsApp na API sem QR Code: código de pareamento e Passkey Raphael Serafim· Publicado em 28 de setembro de 2026· 8 min de leitura Compartilhar # Conectar WhatsApp na API sem QR Code: código de pareamento e Passkey Três jeitos de conectar um número na API não oficial do WhatsApp: QR Code, código de pareamento de 8 caracteres e WAME Passkey. Com cURL, webhooks e reconexão. Copiar para LLM[Ver como Markdown](https://api-wa.me/blog/conectar-whatsapp-codigo-pareamento-sem-qr-code.md) **Dá para conectar um número na API não oficial do WhatsApp sem QR Code: o `POST /{key}/instance/pairing-code` devolve um código que você digita no próprio celular, e para contas que exigem passkey existe o WAME Passkey, um app desktop que aprova o login e envia a sessão para a sua instância.** O QR Code continua disponível, mas deixou de ser o único caminho — e isso muda muito quando quem precisa conectar é o seu cliente, do outro lado do país. Neste guia você vê os três métodos, quando usar cada um, como acompanhar a conexão por webhook e o que fazer quando a sessão cai. ## Por que existem três jeitos de conectar A API não oficial conecta o seu número como um **aparelho vinculado**, igual ao WhatsApp Web ou ao WhatsApp Desktop. O WhatsApp oferece mais de uma forma de vincular um aparelho, e cada uma resolve um problema: | Método | Como funciona | Melhor para | | --- | --- | --- | | QR Code | Escanear uma imagem com o celular | Quem está na frente da tela | | Código de pareamento | Digitar um código no celular | Conexão remota, suporte, onboarding de cliente | | WAME Passkey | App desktop aprova passkey | Contas que exigem biometria/PIN | Nenhum deles exige criar app na Meta, verificar empresa ou aprovar número — é uma das grandes vantagens da camada não oficial. > A camada não oficial da WAME é independente e não é afiliada, endossada ou suportada pelo WhatsApp ou pela Meta. O uso é de responsabilidade de quem envia. ## Antes de tudo: configure os webhooks Conectar é um processo assíncrono — o QR expira e é renovado, a pessoa leva um tempo para digitar o código. Em vez de ficar consultando, receba os eventos. O `PUT /{key}/instance` define para onde cada tipo de evento vai: bash Copiar ``` curl -X PUT "https://us.api-wa.me/SUA_KEY/instance" \ -H "Content-Type: application/json" \ -d '{ "allowWebhook": true, "allowNumber": "all", "webhookQrCode": "https://seusistema.com/wame/qrcode", "webhookConnection": "https://seusistema.com/wame/conexao", "webhookMessage": "https://seusistema.com/wame/mensagens", "webhookFormat": "meta" }' ``` - `webhookQrCode` recebe cada QR Code novo (útil para mostrar no seu painel). - `webhookConnection` avisa quando a instância conecta, desconecta ou faz logout. - `webhookMessage` é onde as mensagens vão chegar depois. ## Método 1: QR Code O clássico. Um `POST` inicia a conexão e devolve o QR Code: bash Copiar ``` curl -X POST "https://us.api-wa.me/SUA_KEY/instance" ``` No celular: **WhatsApp > Aparelhos conectados > Conectar um aparelho**, e escaneie. Se você configurou o `webhookQrCode`, os QR renovados chegam lá automaticamente — mostre sempre o mais recente no seu painel, porque um QR antigo não funciona. Funciona muito bem quando **você** está conectando o seu próprio número. Fica ruim quando você precisa instruir um cliente por telefone a abrir uma tela, achar o QR e apontar a câmera. ## Método 2: código de pareamento Aqui você informa o número que vai conectar e recebe um código curto: bash Copiar ``` curl -X POST "https://us.api-wa.me/SUA_KEY/instance/pairing-code" \ -H "Content-Type: application/json" \ -d '{ "phoneNumber": "5511999999999" }' ``` No celular: **WhatsApp > Aparelhos conectados > Conectar um aparelho > Conectar com número de telefone**, e digite o código. O número deve estar no formato internacional, só com dígitos, e precisa ser o mesmo número do celular onde o código será digitado. Por que isso é tão útil: - **Onboarding remoto.** Você manda o código por e-mail, SMS ou pelo seu painel, e o cliente digita. Nada de videochamada para "mostrar o QR". - **Sem câmera.** Celular com câmera quebrada, tela pequena, pessoa com dificuldade de enquadrar o QR — o código resolve. - **Automatizável.** Seu SaaS pode ter um fluxo "digite seu número → receba o código → conecte", todo dentro do seu produto. Um fluxo típico de onboarding em Node.js: javascript Copiar ``` const BASE = 'https://us.api-wa.me'; // 1. Cliente informa o número no seu painel app.post('/onboarding/whatsapp', async (req, res) => { const { key, telefone } = req.body; // key da instância deste cliente const r = await fetch(`${BASE}/${key}/instance/pairing-code`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ phoneNumber: telefone }), }); // A resposta traz o código em `code` e, em `isConnected`, // se a instância já está conectada. const { code, isConnected } = await r.json(); res.json({ code, isConnected }); // mostre `code` na tela do cliente }); // 2. Webhook de conexão avisa quando terminou app.post('/wame/conexao', (req, res) => { res.sendStatus(200); // Atualize o status do cliente no seu banco e libere o próximo passo }); ``` Se você provisiona instâncias para muitos clientes, esse é o fluxo que mais reduz chamados de suporte. Mais sobre a gestão de várias contas em [provisionar WhatsApp para vários clientes por API](https://api-wa.me/blog/provisionar-whatsapp-multiplos-clientes-api). ## Método 3: WAME Passkey O WhatsApp passou a exigir **passkey** — chave de acesso confirmada por biometria ou PIN do aparelho — para aprovar o login de algumas contas. Como o passkey fica no dispositivo do dono da conta, ele não pode ser aprovado por uma API remota diretamente. O [WAME Passkey](https://api-wa.me/passkey) resolve isso. É um app desktop gratuito e open-source, para macOS, Windows e Linux: 1. Você abre o app no computador; ele abre o WhatsApp Web. 2. Escaneia o QR com o celular e aprova o passkey (biometria ou PIN). 3. O app envia a sessão com segurança para a sua instância, pelo endpoint `POST /{key}/instance/web-session`. A partir daí, a instância funciona como qualquer outra. O endpoint existe na API, mas o caminho recomendado é usar o app — ele cuida da exportação da sessão para você. ## Verificando o estado da conexão A qualquer momento, consulte a instância: bash Copiar ``` curl "https://us.api-wa.me/SUA_KEY/instance" ``` A resposta traz o estado da conexão, se há QR disponível e informações do perfil. Use isso num health check do seu painel, e não num loop de alguns segundos — para mudanças em tempo real, o `webhookConnection` é o caminho. ## Quando a sessão cai: reiniciar vs desconectar Duas operações que parecem parecidas e não são: bash Copiar ``` # Reiniciar: recarrega a instância mantendo a sessão (não precisa de QR de novo) curl -X POST "https://us.api-wa.me/SUA_KEY/instance/restart" # Desconectar: faz logout e apaga a autenticação (precisa conectar de novo) curl -X DELETE "https://us.api-wa.me/SUA_KEY/instance" ``` Na dúvida, **reinicie antes de desconectar**. O `DELETE` é definitivo: a sessão sai da lista de aparelhos conectados e você volta ao QR, ao código ou ao Passkey. Em quedas temporárias de rede, a WAME reconecta sozinha com espaçamento crescente e aleatório entre as tentativas, para evitar uma rajada de reconexões simultâneas — um dos sinais que o WhatsApp observa. Isso faz parte da camada de anti-detecção da plataforma, junto com a identidade de dispositivo única por instância e coerente com o país do número. É um dos motivos pelos quais a taxa de bloqueio é muito baixa para quem usa do jeito certo; os detalhes estão em [anti-detecção na API não oficial](https://api-wa.me/blog/anti-deteccao-api-whatsapp-nao-oficial). Uma regra importante: se a instância recebeu **logout** (e não uma queda temporária), não fique reconectando em loop. Descubra o motivo antes. Insistir num número restrito piora a situação — veja [os sinais de que o número está em risco](https://api-wa.me/blog/sinais-numero-whatsapp-risco-bloqueio) e [o que fazer se o número foi bloqueado](https://api-wa.me/blog/numero-bloqueado-whatsapp-o-que-fazer). ## E se eu não quiser usar celular nenhum? Os três métodos acima vinculam a API a um WhatsApp que existe num celular. Existe ainda um quarto caminho: registrar o número **direto na API**, sem instalar o app, recebendo o código de verificação por SMS ou ligação. É outro fluxo, com outros endpoints — explicado em [WhatsApp sem celular: registrar um número pela API](https://api-wa.me/blog/whatsapp-sem-celular-conexao-mobile-api). ## Conclusão Conectar um número na API não oficial do WhatsApp não depende mais de apontar uma câmera para a tela. O código de pareamento torna o onboarding remoto e automatizável, o WAME Passkey resolve contas que exigem biometria e o QR Code continua lá para quem está na frente do computador. Com os webhooks de QR e de conexão configurados, o processo inteiro vira um fluxo do seu produto — sem aprovação da Meta, sem template, sem espera. Veja os próximos passos em [API não oficial do WhatsApp: recursos e exemplos](https://api-wa.me/blog/api-nao-oficial-whatsapp-recursos-exemplos) e todos os parâmetros na [documentação](https://api-wa.me/docs). ### Pronto para automatizar seu WhatsApp? Crie sua conta gratuita e comece a enviar mensagens pela API em minutos. [Começar grátis](https://portal.api-wa.me/sign-up) ## Perguntas frequentes Dá para conectar o WhatsApp na API sem escanear QR Code?+ Sim. Na WAME API, o POST /{key}/instance/pairing-code com o phoneNumber gera um código de pareamento que você digita no próprio celular, em Aparelhos conectados > Conectar com número de telefone. Não precisa de câmera nem de estar na frente da tela. Qual a diferença entre QR Code e código de pareamento?+ O resultado é o mesmo: o número fica conectado à instância como um aparelho vinculado. O QR Code exige escanear uma imagem; o código de pareamento é um texto curto digitado no celular, o que facilita conectar remotamente — por exemplo, quando o cliente está em outra cidade. O que é o WAME Passkey?+ É um app desktop gratuito e open-source (macOS, Windows e Linux) para contas em que o WhatsApp passou a exigir passkey — biometria ou PIN do aparelho — para aprovar o login. Ele abre o WhatsApp Web, você aprova a chave de acesso no celular e a sessão é enviada com segurança para a sua instância. Como sei que a instância conectou?+ Configure o webhookConnection pelo PUT /{key}/instance para receber o evento de mudança de conexão, ou consulte GET /{key}/instance, que devolve o estado atual da conexão e informações do perfil. Preciso manter o celular ligado depois de conectar?+ Não para o funcionamento do dia a dia: a sessão de aparelho vinculado funciona com o celular desligado. Mas o número precisa continuar ativo no aplicativo principal. Se o aparelho ficar muito tempo sem abrir o WhatsApp, o próprio app pode desconectar os aparelhos vinculados. ## Continue lendo [### Conectar o WhatsApp à API só pelo celular, sem QR Code (código de 8 dígitos) Só tem o celular? Conecte seu WhatsApp à API sem QR Code: gere o código de 8 dígitos no painel WAME e digite no app. Passo a passo e soluções.](https://api-wa.me/blog/conectar-whatsapp-api-pelo-celular-sem-qr-code)[### Onboarding de WhatsApp no seu SaaS com código de pareamento (sem QR, com a sua marca) Conecte o WhatsApp do cliente dentro do seu SaaS, com a sua marca e sem QR Code: fluxo, estados da tela, backend em Node.js e webhook de conexão.](https://api-wa.me/blog/onboarding-saas-whatsapp-codigo-pareamento)[### Agente de voz no WhatsApp: latência, interrupção (barge-in) e silêncio Como deixar um agente de voz no WhatsApp natural: latência, streaming, detecção de fala, interrupção (barge-in), silêncio e eco, com exemplos em Node.js.](https://api-wa.me/blog/agente-voz-whatsapp-latencia-interrupcao) [Voltar ao blog](https://api-wa.me/blog) ## Structured data ```json { "@context": "https://schema.org", "@type": "WebSite", "name": "WAME API", "alternateName": "API Oficial e Não Oficial de WhatsApp, Instagram, Messenger e Telegram", "url": "https://api-wa.me", "inLanguage": "pt-BR", "publisher": { "@id": "https://api-wa.me/#organization", "@type": "Organization", "name": "WAME API", "url": "https://api-wa.me" } } { "@context": "https://schema.org", "@type": "Organization", "@id": "https://api-wa.me/#organization", "name": "WAME API", "alternateName": [ "WAME", "Wame API", "wame.api.br", "api-wa.me" ], "url": "https://api-wa.me", "logo": { "@type": "ImageObject", "url": "https://api-wa.me/images/web-app-manifest-512x512.png", "width": 512, "height": 512 }, "disambiguatingDescription": "WAME API é uma empresa brasileira de software, fundada em 2017 e parceira oficial da Meta (Meta Business Partner), que fornece APIs de WhatsApp, Instagram Direct e Messenger. Não tem relação com o wa.me, que é o encurtador de links operado pela WhatsApp LLC.", "identifier": { "@type": "PropertyValue", "propertyID": "INPI-BR", "name": "Pedido de registro de marca (INPI, classe NCL 42)", "value": "944724159" }, "foundingDate": "2017", "slogan": "Parceira Oficial da Meta — WhatsApp, Instagram, Messenger e Telegram numa instância só. Desde 2017.", "description": "Plataforma brasileira e Parceira Oficial da Meta (Meta Business Partner) para as APIs oficiais de WhatsApp (Cloud API), Instagram Direct e Messenger — os três numa única instância, com os mesmos endpoints e um único formato de webhook. Também oferece a API não oficial via QR Code e o Telegram, na mesma plataforma. No mercado desde 2017, com mais de 50 mil instâncias criadas, 99,9% de uptime e suporte humano 24/7 em português. SDKs oficiais para Node.js/TypeScript e PHP.", "knowsAbout": [ "WhatsApp Cloud API oficial (Meta)", "API oficial de Instagram (Direct)", "API oficial de Messenger", "API multicanal Meta", "Meta Business Partner", "WhatsApp API", "API não oficial de WhatsApp", "automação de WhatsApp", "números virtuais", "webhooks" ], "sameAs": [ "https://github.com/wame-api", "https://www.linkedin.com/company/wameapi", "https://www.instagram.com/wame.api/", "https://www.youtube.com/@wameapi" ], "contactPoint": { "@type": "ContactPoint", "contactType": "customer support", "url": "https://api-wa.me/contact", "availableLanguage": [ "Portuguese" ] } } { "@context": "https://schema.org", "@type": "BlogPosting", "headline": "Conectar WhatsApp na API sem QR Code: código de pareamento e Passkey", "description": "Três jeitos de conectar um número na API não oficial do WhatsApp: QR Code, código de pareamento de 8 caracteres e WAME Passkey. Com cURL, webhooks e reconexão.", "image": "https://api-wa.me/blog/conectar-whatsapp-codigo-pareamento-sem-qr-code/opengraph-image", "datePublished": "2026-09-28", "dateModified": "2026-09-28", "author": { "@type": "Person", "name": "Raphael Serafim", "url": "https://github.com/raphaelvserafim", "sameAs": [ "https://github.com/raphaelvserafim" ] }, "publisher": { "@type": "Organization", "name": "api-wa.me", "logo": { "@type": "ImageObject", "url": "https://api-wa.me/images/screenshot.png" } }, "mainEntityOfPage": { "@type": "WebPage", "@id": "https://api-wa.me/blog/conectar-whatsapp-codigo-pareamento-sem-qr-code" }, "keywords": "api whatsapp não oficial, api não oficial whatsapp, conectar whatsapp sem qr code, código de pareamento whatsapp, pairing code whatsapp api, whatsapp passkey api, conectar whatsapp api", "inLanguage": "pt-BR" } { "@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://api-wa.me" }, { "@type": "ListItem", "position": 2, "name": "Blog da API do WhatsApp", "item": "https://api-wa.me/blog" }, { "@type": "ListItem", "position": 3, "name": "Conectar WhatsApp na API sem QR Code: código de pareamento e Passkey", "item": "https://api-wa.me/blog/conectar-whatsapp-codigo-pareamento-sem-qr-code" } ] } { "@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [ { "@type": "Question", "name": "Dá para conectar o WhatsApp na API sem escanear QR Code?", "acceptedAnswer": { "@type": "Answer", "text": "Sim. Na WAME API, o POST /{key}/instance/pairing-code com o phoneNumber gera um código de pareamento que você digita no próprio celular, em Aparelhos conectados > Conectar com número de telefone. Não precisa de câmera nem de estar na frente da tela." } }, { "@type": "Question", "name": "Qual a diferença entre QR Code e código de pareamento?", "acceptedAnswer": { "@type": "Answer", "text": "O resultado é o mesmo: o número fica conectado à instância como um aparelho vinculado. O QR Code exige escanear uma imagem; o código de pareamento é um texto curto digitado no celular, o que facilita conectar remotamente — por exemplo, quando o cliente está em outra cidade." } }, { "@type": "Question", "name": "O que é o WAME Passkey?", "acceptedAnswer": { "@type": "Answer", "text": "É um app desktop gratuito e open-source (macOS, Windows e Linux) para contas em que o WhatsApp passou a exigir passkey — biometria ou PIN do aparelho — para aprovar o login. Ele abre o WhatsApp Web, você aprova a chave de acesso no celular e a sessão é enviada com segurança para a sua instância." } }, { "@type": "Question", "name": "Como sei que a instância conectou?", "acceptedAnswer": { "@type": "Answer", "text": "Configure o webhookConnection pelo PUT /{key}/instance para receber o evento de mudança de conexão, ou consulte GET /{key}/instance, que devolve o estado atual da conexão e informações do perfil." } }, { "@type": "Question", "name": "Preciso manter o celular ligado depois de conectar?", "acceptedAnswer": { "@type": "Answer", "text": "Não para o funcionamento do dia a dia: a sessão de aparelho vinculado funciona com o celular desligado. Mas o número precisa continuar ativo no aplicativo principal. Se o aparelho ficar muito tempo sem abrir o WhatsApp, o próprio app pode desconectar os aparelhos vinculados." } } ] } ```