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

integração

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.

Teste com o time técnico do seu lado

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time da D-API acompanha a integração no seu produto.

Leia também

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.