Migrar de Z-API a ZapZap: mapa de endpoints y paso a paso

Sigue igual: conectas un número de WhatsApp por código QR y usas una API HTTP con JSON para enviar y un webhook para recibir. Los dos son soluciones no oficiales, sin sello de Meta, y en ambos el número puede ser limitado o bloqueado si el uso es abusivo.

Cambia: la autenticación (Z-API usa el encabezado Client-Token; ZapZap usa x-api-key y x-api-secret), los nombres de los campos (phone y message en Z-API; number y text en ZapZap), el formato del webhook y el modelo de precio. Según el sitio de Z-API el 27/10/2026, el plan Ultimate cuesta R$99,99 por instancia al mes y el Partner, para 10 o más instancias, R$89,99. ZapZap cobra R$15 por número activo al mes, sin cobro por mensaje. Los planes tienen funciones distintas, así que compara lo que realmente usas antes de decidir.

La tabla cubre lo que casi todo proyecto usa. Para el resto, la referencia de ZapZap lista todos los endpoints. La columna de Z-API viene de su documentación (developer.z-api.io, 27/10/2026); donde la página no traía el dato, la celda dice que se revise.

En cada fila, lee las referencias de Enviar Texto, Enviar Multimedia y Verificar Número antes de cambiar.

El cambio de envío es mecánico. Cambia la URL, quita el Client-Token, agrega los dos encabezados de ZapZap y renombra los campos. El número sigue con código de país y solo dígitos.

Crea una función delgada en tu código (enviarWhatsApp(numero, texto)) y cambia solo lo que hay dentro. Así la migración queda en un punto, y volver atrás también.

// 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 }
}

En Z-API, el mensaje recibido llega con campos en el nivel superior, como phone, fromMe, messageId, instanceId y text.message (documentación de callbacks, 27/10/2026). En ZapZap, el evento viene en un sobre: event, data.message.text, data.message.chatid y data.message.fromMe, además de delivery_id e instance_id.

Escribe un adaptador que convierta el evento de ZapZap al formato interno que tu sistema ya entiende. Así el resto del código no cambia. Configura la URL en configurar webhook, activa solo el evento messages y valida la firma según la guía de webhook en producción.

// 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,
  };
}

El número es tuyo: en ZapZap creas una instancia (Crear Instancia) y conectas el mismo número por código QR. El historial de conversaciones del otro servicio no se migra por API; guarda lo que necesites antes. Un mismo número no debe estar activo en los dos servicios a la vez, así que planifica una ventana corta de cambio, de preferencia fuera del horario pico.

Lista: 1) crear la cuenta y la instancia; 2) probar envío y recepción con un número tuyo; 3) cambiar la función de envío; 4) apuntar el webhook y validar la firma; 5) hacer el cambio en un horario tranquilo; 6) desconectar la instancia antigua solo después de confirmar el flujo nuevo; 7) seguir las primeras horas por los logs y por las entregas del webhook.

Z-API tiene documentación extensa, soporte nacional y, según su sitio, el plan Ultimate sin límite de mensajes y sin costo por mensaje. Si tu uso depende de una función específica suya que ZapZap no tiene, o si la operación es estable y el costo tiene sentido, migrar puede no valer el esfuerzo. Si necesitas un canal homologado por Meta, ninguna de las dos sirve: la opción es la API oficial. La comparativa Z-API y ZapZap detalla precio y límites con fuente y fecha.