API oficial e não oficial WhatsApp na mesma integração
Ofereça API oficial e não oficial WhatsApp no seu SaaS com um só código: escolha o tipo de conexão por cliente e mantenha um único handler de webhooks.
Time D-API. Atualizado em .8 min de leitura.
Um SaaS que vende WhatsApp atende clientes com necessidades diferentes. A clínica pequena quer conectar o número que já usa no celular e começar a atender no mesmo dia; a rede de franquias quer templates aprovados, número verificado e a cobrança da Meta na própria conta. Oferecer API oficial e não oficial WhatsApp no mesmo produto atende os dois perfis, desde que a escolha aconteça por cliente final e o seu código continue sendo um só.
O problema aparece quando cada tipo de conexão traz sua própria integração: dois clientes HTTP, dois formatos de webhook, duas tabelas de mensagens e dois caminhos de suporte. O time passa a manter o produto em dobro, e cada feature nova precisa ser escrita duas vezes. Este artigo mostra como estruturar o SaaS para que a escolha da API vire um campo no cadastro do cliente, decidido pelo time comercial, sem tocar no código.
A base técnica vem da D-API, que reúne as duas modalidades no mesmo ecossistema e na mesma implementação, com 1.875 conexões em 4 datacenters no Brasil.
O que cada API entrega para o seu cliente
Quando o time comercial sabe o que cada modalidade resolve, ele oferece a opção certa sem abrir chamado para a engenharia. A comparação abaixo cobre o que pesa na decisão do cliente final.
API não oficial
A API não oficial conecta o número que o cliente já usa, lendo um QR code de pareamento ou digitando um código de pareamento. A ativação leva minutos, não depende de aprovação de template e o custo fica restrito à conexão. Na D-API ela inclui ligações de WhatsApp, para fazer e receber, sem custo extra, o que pesa para quem vende atendimento.
Ela funciona bem para atendimento e vendas consultivas, negócios pequenos e médios e clientes que querem começar hoje, com o número que já está no cartão de visita.
API Oficial (Cloud API)
A API Oficial roda na infraestrutura da Meta. O cliente passa pelo Embedded Signup, o número fica ligado a uma WABA e as mensagens iniciadas pela empresa fora da janela de atendimento usam templates aprovados. A Meta cobra as mensagens à parte, direto na conta do cliente.
Ela atende empresas com exigência de compliance, operações com volume alto de notificações e quem quer manter o app WhatsApp Business no mesmo número usando coexistência.
| Critério | API não oficial | API Oficial |
|---|---|---|
| Como conecta | QR code ou código de pareamento | Embedded Signup da Meta |
| Mensagem iniciada pela empresa | Texto livre | Template aprovado fora da janela |
| Tarifa de mensagem | Não há | Cobrada pela Meta na WABA do cliente |
| Ligações de WhatsApp | Incluídas, sem custo extra | Não disponíveis na D-API |
| Preço da conexão na D-API | Mesmo valor | Mesmo valor |
O tipo de conexão vira um atributo do tenant
O ganho para o SaaS está aqui: a decisão entre as duas APIs acontece uma vez, no onboarding do cliente, e fica registrada como um campo. Depois disso, todo o restante do produto conversa com um identificador único, o sessionId.
O modelo de dados fica simples. Cada tenant tem uma ou mais conexões, e cada conexão guarda o sessionId e o tipo. Em um produto multi-tenant, esse mapeamento é o que liga o evento que chega ao cliente certo. O artigo sobre API WhatsApp multi-tenant aprofunda o isolamento entre clientes.
Criando uma conexão não oficial
Para a não oficial, o backend cria a sessão com um sessionId escolhido por você. Usar o id do tenant no nome facilita a leitura de logs.
curl -X POST https://api.d-api.cloud/api/v1/sessions \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "sessionId": "acme-42-principal", "type": "unofficial" }'
Em seguida o seu frontend busca o QR code em GET /api/v1/sessions/{sessionId}/qr e mostra na tela para o cliente escanear em Aparelhos conectados.
Criando uma conexão oficial
Para a oficial, o frontend abre o fluxo de conexão com o pacote d-api-sdk. O Embedded Signup roda numa página hospedada pela D-API, aberta como popup, então o seu domínio não precisa ser cadastrado na Meta. A publishable key usada aqui só inicia o onboarding: ela não envia mensagens nem lê dados, por isso pode ficar no navegador.
import { DApiConnect } from "d-api-sdk/connect";
const connect = new DApiConnect({ publishableKey: "pk_live_…" });
const { connectionId } = await connect.start({
webhookUrl: "https://seu-saas.com/hooks/dapi",
webhookMode: "normalized",
metadata: { tenantId: "acme-42" },
});
O connectionId devolvido é o sessionId da conexão oficial nas rotas de envio. Guarde-o no tenant, ao lado do tipo cloud_api, e o onboarding está concluído.
O resultado também chega pelo webhook session.created, com o seu metadata intacto em data.metadata. Isso importa no celular: em navegador mobile o popup abre como aba, o retorno por postMessage pode não acontecer e o start() pode rejeitar mesmo com a conexão criada. Trate o session.created como confirmação definitiva e use o tenantId do metadata para ligar a conexão ao cliente.
Uma rota de envio para as duas APIs
Com o sessionId em mãos, o envio de texto usa a mesma rota, seja a conexão oficial ou não. O serviço de mensagens do seu SaaS não precisa saber qual modalidade está do outro lado.
curl -X POST https://api.d-api.cloud/api/v1/messages/send/text \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "acme-42-principal",
"to": "5511999999999",
"text": "Seu pedido saiu para entrega."
}'
A única regra que depende do tipo é a das mensagens iniciadas pela empresa. Na API Oficial, fora da janela de 24 horas, a Meta exige template aprovado, enviado por POST /api/v1/messages/send/template. Concentre essa decisão em um único ponto do código, que olha o tipo da conexão e o estado da janela, e o resto do produto continua chamando a mesma função de envio.
Um handler de webhook para os dois tipos
Manter um só handler corta pela metade o trabalho de evoluir o produto: uma feature de inbox, um gatilho de automação ou um relatório escrito uma vez funciona para todos os clientes. O webhookMode: "normalized", padrão nas conexões oficiais, entrega o evento canônico da D-API, o mesmo payload de uma conexão não oficial.
Todo evento traz event, sessionId e data no mesmo lugar. Nas conexões não oficiais, o envelope também leva timestamp e traceId:
{
"event": "messages.received",
"sessionId": "acme-42-principal",
"data": { "...": "específico do evento" },
"timestamp": "2026-01-24T22:51:32.601Z",
"traceId": "c17dee440402792623e3ad6d925cb000"
}
Como o sessionId vem em todo evento, você pode apontar todas as conexões, oficiais e não oficiais, para um único endpoint e distribuir pelo tenant. Um handler mínimo em TypeScript confirma o recebimento rápido e joga o processamento para uma fila:
app.post("/hooks/dapi", async (req, res) => {
const { event, sessionId, data, traceId } = req.body;
const tenant = await tenants.findBySessionId(sessionId);
if (!tenant) return res.sendStatus(200);
await queue.publish("whatsapp-events", { tenantId: tenant.id, event, data, traceId });
res.sendStatus(200);
});
Responder 2xx logo importa porque cada tentativa de entrega tem timeout de 30 segundos e falhas entram em até 7 retentativas com backoff exponencial. Quando presente, o traceId vai junto para o log e facilita o rastreio quando o suporte precisar. O guia de webhooks da API de WhatsApp detalha eventos, retentativas e deduplicação.
Se o seu time já tem um parser do formato oficial da Meta, a conexão aceita webhookMode: "meta_passthrough", que entrega o corpo cru do webhook da Meta. Dá para trocar o modo depois pela rota PATCH /api/v1/connections/cloud-api/{id}, sem refazer o onboarding do cliente.
O custo de cada escolha fica previsível
Para o SaaS, a conta da plataforma não muda com a modalidade: na D-API a conexão da API Oficial custa o mesmo que a não oficial, com preço por conexão que cai com o volume (veja em /#preco). O que muda é a tarifa de mensagem da Meta, que existe só na oficial e é cobrada na WABA do cliente final, com o método de pagamento dele.
Isso permite montar a oferta comercial sem margem escondida. O cliente que escolhe a oficial sabe que vai receber a fatura da Meta, e o seu plano cobra a mesma coisa pela conexão nos dois casos. O artigo sobre quanto custa a API Oficial explica as categorias de cobrança e as formas de repassar o custo.
Trocar um cliente de API sem retrabalho
Clientes mudam de perfil. A loja que começou com a não oficial cresce, passa a disparar notificações em volume e pede a oficial. Com o mesmo contrato de envio e de webhook, a troca vira uma operação de cadastro.
O fluxo fica assim: o cliente conecta o número pela API Oficial no seu painel, o session.created chega com o tenantId no metadata, e o seu backend atualiza a conexão ativa do tenant para o novo sessionId. O histórico de conversas que você já guarda no seu banco continua onde está, e as automações seguem disparando porque consomem o mesmo formato de evento.
O caminho inverso também é possível, para quem quer conversar sem template ou usar ligações incluídas. Em ambos os casos, o trabalho de engenharia acontece uma vez, quando você implementa os dois fluxos de onboarding.
Por onde começar
Comece pelo modelo de dados: um campo de tipo na conexão do tenant e o sessionId como chave de tudo. Depois implemente os dois onboardings, o QR code para a não oficial e o popup do DApiConnect para a oficial, ambos gravando no mesmo lugar.
Em seguida, escreva um único handler de webhook com webhookMode: "normalized" e um único serviço de envio que decide entre texto e template conforme a janela. Com isso, a escolha entre API oficial e não oficial passa a ser uma conversa comercial com o cliente. O passo a passo completo do fluxo oficial está na documentação da D-API.
Veja também: Integração, API de WhatsApp.
Perguntas frequentes
Preciso de duas integrações para oferecer API oficial e não oficial no meu SaaS?
Na D-API, não. As duas modalidades usam o mesmo sessionId nas rotas de envio e, com webhookMode normalized, o mesmo formato de evento. O que muda é só o fluxo de conexão: QR code ou código de pareamento na não oficial, Embedded Signup na oficial.
A conexão da API Oficial custa mais caro que a não oficial?
Na D-API, a conexão da API Oficial custa o mesmo que a não oficial. As tarifas de mensagem da Meta são cobradas à parte, na conta Meta (WABA) do seu cliente final.
Meu domínio precisa estar cadastrado na Meta para usar o Embedded Signup?
Não precisa. O fluxo roda numa página hospedada pela D-API, aberta como popup a partir do seu frontend, e o resultado volta para o seu app por postMessage e pelo webhook session.created.
Posso mudar um cliente da API não oficial para a oficial depois?
Pode. O cliente cria a nova conexão pelo fluxo da API Oficial e você atualiza o sessionId associado ao tenant. Como envio e webhooks seguem o mesmo contrato, o resto do seu código continua igual.
Já tenho um parser do webhook da Meta. Preciso jogá-lo fora?
Não. Configure a conexão com webhookMode meta_passthrough e o corpo cru do webhook da Meta chega no seu endpoint sem tradução. Dá para trocar o modo depois pela rota de atualização da conexão.