A diferença em uma frase
Na oficial, você opera dentro das regras e da cobrança da Meta, em troca de estabilidade e respaldo. Na não oficial, você opera o próprio WhatsApp do número, com liberdade e custo previsível, em troca de assumir a responsabilidade pelo comportamento de envio. As duas são formas legítimas de ter uma API de WhatsApp; o erro é escolher sem olhar o cenário.
Comparativo por critério
| Critério | Oficial (Cloud API) | Não oficial (QR) |
|---|---|---|
| Tempo até a primeira mensagem | Depende de cadastro e verificação na Meta | Minutos: criar sessão e ler o QR |
| Número | Registrado na plataforma da Meta, conforme as regras dela | O número atual, que continua no celular |
| Iniciar conversa | Só com template aprovado | Mensagem livre |
| Cobrança | Por template, varia por categoria e país, mais taxa do provedor | Por conexão, sem custo por mensagem |
| Grupos | Limitados | Criar, gerenciar participantes, enviar |
| Risco de bloqueio | Baixo dentro das regras da Meta | Depende do padrão de envio e da infraestrutura |
| Selo e perfil verificado | Possível, conforme critérios da Meta | Não se aplica |
| Dependência | Regras e prazos da Meta | Qualidade do provedor |
Quando escolher cada uma
Escolha a oficial quando
- Você precisa iniciar conversa com quem nunca falou com você, em escala, como avisos para uma base grande. Template aprovado é o caminho previsto para isso.
- O seu cliente ou o seu setor exige. Bancos, seguradoras e empresas com área de compliance costumam pedir o canal oficial por contrato.
- O número é a marca. Um número central de atendimento, com perfil verificado, que não pode correr risco de bloqueio.
Escolha a não oficial quando
- Cada cliente seu conecta o próprio número. É o caso típico de SaaS: o cliente lê um QR na sua tela e começa a usar, sem passar por cadastro na Meta.
- A conversa é contínua e já existe relação. Atendimento, follow-up comercial, confirmação de agenda, suporte.
- Você precisa de grupos ou de recursos do aplicativo comum que a oficial não cobre.
- O custo por mensagem inviabiliza o modelo de negócio, como em operações com alto volume de mensagens por número.
Use as duas quando
O cenário mais comum em produtos maduros é misto: a maioria dos clientes na não oficial, pela velocidade de ativação e pelo custo, e alguns na oficial, por exigência deles ou para um fluxo específico, como notificações para quem ainda não iniciou conversa. Isso só é viável se a integração não precisar ser duplicada.
Na D-API, as duas usam a mesma API
A diferença fica na criação da sessão. O campo type aceita unofficial ou cloud_api, e o sessionId resultante funciona nas mesmas rotas de envio:
# Não oficial: conecta depois por QR
curl -X POST https://api.d-api.cloud/api/v1/sessions \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "sessionId": "loja-sp", "type": "unofficial" }'
# Oficial: usa os dados da conta na Meta
curl -X POST https://api.d-api.cloud/api/v1/sessions \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "matriz-oficial",
"type": "cloud_api",
"wabaId": "SEU_WABA_ID",
"phoneNumberId": "SEU_PHONE_NUMBER_ID",
"accessToken": "SEU_ACCESS_TOKEN"
}'Depois disso, um envio de texto para loja-sp ou para matriz-oficial é a mesma chamada em /api/v1/messages/send/text. Na conexão oficial, o webhook pode vir no formato normalizado, igual ao da não oficial, ou no formato original da Meta, se o seu sistema já trabalha com ele.
O que é exclusivo de um modelo continua exclusivo. O envio de template aprovado, em /api/v1/messages/send/template, só funciona em conexões cloud_api; numa sessão não oficial, a API responde com erro 400 e o código NOT_CLOUD_API. Isso deixa explícito, no próprio código, qual fluxo depende de qual modelo.
Custo, risco e o que ninguém conta
Dois pontos costumam ficar de fora das comparações. O primeiro: na oficial, o que determina o custo não é quantos números você tem, e sim quantas conversas você inicia. Um produto que manda lembretes todos os dias para uma base grande sente isso rápido. O detalhamento está em quanto custa uma API de WhatsApp.
O segundo: na não oficial, o risco de bloqueio não é uma loteria. Ele depende de consentimento, volume e conteúdo, e a infraestrutura reduz o estrago quando algo dá errado. Na D-API, cada conexão roda isolada e com IP próprio, então o problema de um número não contamina os outros. As práticas que mais fazem diferença estão em como evitar banimento na API de WhatsApp.
Para ir fundo em cada modelo, veja as páginas da API oficial de WhatsApp e da API não oficial de WhatsApp.