Migrar da Z-API para a ZapZap: mapa de endpoints e passo a passo

Continua igual: você conecta um número de WhatsApp por QR code e usa uma API HTTP com JSON para enviar e um webhook para receber. Os dois são soluções não oficiais, sem selo da Meta, e nos dois o número pode ser limitado ou bloqueado se o uso for abusivo.

Muda: a autenticação (a Z-API usa o cabeçalho Client-Token; a ZapZap usa x-api-key e x-api-secret), os nomes dos campos (phone e message na Z-API; number e text na ZapZap), o formato do webhook e o modelo de preço. Segundo o site da Z-API em 27/10/2026, o plano Ultimate custa R$99,99 por instância por mês e o Partner, para 10 ou mais instâncias, R$89,99. A ZapZap cobra R$15 por número ativo ao mês, sem cobrança por mensagem. Os planos têm recursos diferentes, então compare o que você usa de fato antes de decidir.

A tabela cobre o que quase todo projeto usa. Para o resto, a referência da ZapZap lista todos os endpoints. A coluna da Z-API vem da documentação dela (developer.z-api.io, 27/10/2026); onde a página não trazia o dado, a célula diz para conferir.

Em cada linha, leia a referência de Enviar Texto, Enviar Mídia e Verificar Número antes de trocar.

A mudança de envio é mecânica. Troque a URL, remova o Client-Token, acrescente os dois cabeçalhos da ZapZap e renomeie os campos. O número continua com DDI e só dígitos.

Crie uma função fina no seu código (enviarWhatsApp(numero, texto)) e troque só o que está dentro dela. Assim a migração fica em um ponto, e voltar atrás também.

// ANTES: Z-API (confira a URL e o corpo na documentação da Z-API)
// headers: { "Client-Token": process.env.ZAPI_CLIENT_TOKEN }
// body:    { phone: "5511999999999", message: "Olá!" }

// DEPOIS: ZapZap
export async function enviarWhatsApp(numero, texto) {
  const r = await fetch(
    "https://api.zapzapapi.com/api/v1/" + process.env.ZAPZAP_INSTANCE_ID + "/send/text",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": process.env.ZAPZAP_API_KEY,
        "x-api-secret": process.env.ZAPZAP_API_SECRET,
      },
      body: JSON.stringify({ number: numero, text: texto }),
      signal: AbortSignal.timeout(15000),
    }
  );
  if (!r.ok) throw new Error("ZapZap " + r.status + " " + (await r.text()));
  return r.json(); // { messageId, status }
}

Na Z-API, a mensagem recebida chega com campos no topo, como phone, fromMe, messageId, instanceId e text.message (documentação de callbacks, 27/10/2026). Na ZapZap, o evento vem num envelope: event, data.message.text, data.message.chatid e data.message.fromMe, além de delivery_id e instance_id.

Escreva um adaptador que converta o evento da ZapZap para o formato interno que o seu sistema já entende. Assim o resto do código não muda. Configure a URL em configurar webhook, ligue só o evento messages e valide a assinatura conforme o guia de webhook em produção.

// Converte o evento da ZapZap para o formato que o seu sistema já usa
export function deZapZap(evento) {
  const m = evento?.data?.message;
  if (evento?.event !== "messages" || !m || m.fromMe) return null;
  return {
    telefone: String(m.chatid || "").replace(/\D/g, ""),
    texto: m.text || "",
    idMensagem: evento.event_id || evento.delivery_id,
  };
}

O número é seu: na ZapZap você cria uma instância (Criar Instância) e conecta o mesmo número por QR code. O histórico de conversas do outro serviço não é migrado por API; guarde o que precisar exportar antes. Um mesmo número não deve ficar ativo nos dois serviços ao mesmo tempo, então planeje uma janela curta de troca, de preferência fora do horário de pico.

Checklist: 1) criar a conta e a instância; 2) testar envio e recebimento com um número seu; 3) trocar a função de envio; 4) apontar o webhook e validar a assinatura; 5) fazer a virada em horário calmo; 6) desconectar a instância antiga só depois de confirmar o fluxo novo; 7) acompanhar as primeiras horas pelos logs e por entregas do webhook.

A Z-API tem documentação extensa, suporte nacional e, segundo o site dela, o plano Ultimate sem limite de mensagens e sem custo por mensagem. Se o seu uso depende de um recurso específico dela que a ZapZap não tem, ou se a operação está estável e o custo faz sentido, migrar pode não valer o esforço. Se você precisa de canal homologado pela Meta, nenhuma das duas serve: a opção é a API oficial. O comparativo Z-API x ZapZap detalha preço e limites com fonte e data.