Enviar a verificação por WhatsApp

Entregue a jornada no celular do titular por mensagem, sem deixar a credencial passar pelo WhatsApp.

O titular não está na sua tela: está num call center, num cadastro por telefone, ou abandonou o formulário ontem. O WhatsApp entrega a jornada no aparelho que tem a câmera boa.

Stack	Node 20 · WhatsApp Cloud API (Meta)
Você terá	um link curto do seu domínio na mensagem, e a credencial nunca fora do seu servidor

Confira o exemplo

Os arquivos desta POC, com o destino de cada um.

A credencial não vai na mensagem

A entry.url carrega o acesso à jornada. Ela sai do seu backend para o titular daquela verificação e para mais ninguém — e uma mensagem fica no histórico do aparelho, do WhatsApp Web aberto no computador da loja, e do backup em nuvem.

Então o que viaja é um link curto do seu domínio, que só o seu servidor sabe trocar pela entry.url:

1. Crie a verificação e guarde a entry

   A entry.url fica no seu banco, junto com um token opaco e um prazo.

2. Mande o token, não a URL

   A mensagem leva https://seu-dominio/v/<token>.

3. Troque no clique

   A sua rota valida o token, marca como usado e redireciona para a entry.url.

Isso também é o que o template de botão do WhatsApp permite: a URL base é fixa e aprovada pela Meta, e só o sufixo é variável. Você não conseguiria mandar a entry.url inteira nem se quisesse.

Criar e despachar

app/api/verifications/whatsapp/route.ts

import { randomBytes } from "node:crypto";

export async function POST(request: Request) {
  const operator = await authenticate(request);
  const { registrationId } = await request.json();

  const registration = await db.registrations.byId(registrationId);

  // O telefone vem do CADASTRO, nunca do corpo da requisição: quem escolhe o número escolhe
  // para quem a jornada vai.
  if (!registration.phone_verified) {
    return Response.json({ error: "phone_not_verified" }, { status: 409 });
  }

  const response = await fetch("https://api.legitimuz.com/public/verifications", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.LEGITIMUZ_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      schema_version: "1.0",
      ref_id: registration.id,
      document: { type: "cpf", number: registration.cpf },
      flow_public_id: process.env.LEGITIMUZ_FLOW_ID!,
    }),
  });

  const { verification, entry } = await response.json();

  if (entry.kind !== "web") {
    return Response.json({ error: "entry_not_web" }, { status: 409 });
  }

  // O token é o que vai para o WhatsApp. A `entry.url` fica aqui.
  const token = randomBytes(16).toString("base64url");

  await db.links.create({
    token,
    url: entry.url,
    registration_id: registration.id,
    expires_at: verification.expires_at,
    used_at: null,
  });

  await sendTemplate(registration.phone, registration.first_name, token);

  return Response.json({ sent: true, expiresAt: verification.expires_at });
}

A mensagem

O WhatsApp exige um template aprovado para mensagem iniciada pela empresa. Registre um com botão de URL dinâmica, cuja base é o seu domínio:

Template aprovado na Meta

Nome:   identity_verification
Corpo:  Olá, {{1}}! Para concluir seu cadastro, confirme sua identidade. O link vale por 24 horas
        e é só para você.
Botão:  URL dinâmica — https://seu-dominio/v/{{1}}

lib/whatsapp.ts

const GRAPH = "https://graph.facebook.com/v21.0";

export async function sendTemplate(phone: string, name: string, token: string) {
  const response = await fetch(`${GRAPH}/${process.env.WHATSAPP_PHONE_ID}/messages`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.WHATSAPP_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      messaging_product: "whatsapp",
      to: phone,
      type: "template",
      template: {
        name: "identity_verification",
        language: { code: "pt_BR" },
        components: [
          { type: "body", parameters: [{ type: "text", text: name }] },
          // O sufixo do botão: a base da URL é fixa no template aprovado.
          {
            type: "button",
            sub_type: "url",
            index: "0",
            parameters: [{ type: "text", text: token }],
          },
        ],
      },
    }),
  });

  if (!response.ok) {
    // Não registre o corpo da resposta cru em log: ele repete o telefone do titular.
    throw new Error(`whatsapp_${response.status}`);
  }
}

A rota que troca o token

app/v/[token]/route.ts

export async function GET(_: Request, { params }: { params: { token: string } }) {
  const link = await db.links.consume(params.token);

  // `consume` é um UPDATE condicional, não um SELECT seguido de UPDATE: dois cliques simultâneos
  // no mesmo link não podem resolver os dois.
  if (!link) return new Response("Link inválido ou já usado", { status: 410 });
  if (new Date(link.expires_at) < new Date()) {
    return new Response("Link expirado", { status: 410 });
  }

  // 302 e `no-store`: a URL de destino não pode ficar em cache de proxy nem no histórico do CDN.
  return new Response(null, {
    status: 302,
    headers: { Location: link.url, "Cache-Control": "no-store" },
  });
}

Não faça a rota devolver a entry.url em JSON para o front redirecionar. Isso coloca a credencial no histórico de rede do navegador e em qualquer extensão instalada. O redirecionamento é do servidor.

Antes de enviar para gente de verdade

Regra	Por quê
Só para número já verificado no seu cadastro	quem escolhe o número escolhe o destinatário da jornada
Só com opt-in registrado	mensagem iniciada pela empresa exige consentimento, e a Meta bloqueia quem ignora
Nunca em grupo ou lista de transmissão	a jornada é de uma pessoa; grupo entrega a credencial a todas
Um envio por verificação, com limite de reenvio	reenvio sem teto vira vetor de assédio e custo

Fora da janela de 24 horas de atendimento, a Meta só entrega template aprovado. Dentro dela, a mensagem livre funciona — mas o link curto continua sendo o que você manda.

Antes de rodar

.env

LEGITIMUZ_API_KEY=<SUA_CHAVE>
LEGITIMUZ_WEBHOOK_SECRET=<SEGREDO_DO_ENDPOINT>
LEGITIMUZ_FLOW_ID=<FLOW_PUBLIC_ID>

Variável	Onde achar
LEGITIMUZ_API_KEY	Integrações → Segurança → Chaves de API. Aparece uma vez
LEGITIMUZ_WEBHOOK_SECRET	Integrações → Segurança → Webhooks, na criação do endpoint
LEGITIMUZ_FLOW_ID	Solução KYC → Fluxos, no menu da linha, em Copiar ID do fluxo

Use uma integração sandbox. Nenhum dos três valores vai para o browser ou para o app.

Esta POC precisa também das credenciais da Meta:

.env

WHATSAPP_PHONE_ID=<ID_DO_NUMERO>
WHATSAPP_TOKEN=<TOKEN_DA_APP>

O que esta POC não faz

POC é código para entender o fluxo, não para copiar em produção. Em todas elas, authenticate() é um stub, db é um objeto de mentira e não há migration, observabilidade nem retentativa própria.

• Sem webhook de status do WhatsApp: você não sabe se a mensagem foi lida.
• Sem fallback para SMS quando o número não tem WhatsApp.
• Sem rate limit por cadastro no reenvio.
• Sem migration para a tabela links; ela precisa de índice único em token.

Próximo passo

QR code

A mesma entrega, quando o titular está na sua tela.

Retomada e expiração

O que fazer quando o link expira antes do clique.