El QR de WhatsApp no aparece en la API: qué revisar

La instancia se crea y queda en estado PENDING hasta que se vincula. Para vincularla, pides el QR en QR Code de la instancia y lo lees con el celular en Dispositivos vinculados, como en WhatsApp Web. Cuando la instancia aún no está conectada, la respuesta trae el QR en el campo instance.qrcode. El QR dura poco: si pasa el tiempo, pide otro en lugar de insistir con el anterior.

Si la instancia ya está conectada, la API no genera QR. Confirma el estado y devuelve connected en verdadero, junto con el status de la instancia. Esto le pasa a mucha gente: el panel o tu código espera una imagen y recibe un objeto de status. Antes de depurar cualquier otra cosa, mira el status de la instancia.

BASE="https://api.zapzapapi.com/api/v1"
H1="x-api-key: $ZAPZAP_API_KEY"
H2="x-api-secret: $ZAPZAP_API_SECRET"

# 1) estado atual: disconnected, connecting ou connected
curl "$BASE/$INSTANCE_ID/instance/status" -H "$H1" -H "$H2"

# 2) QR code (só vem se a instância ainda não estiver conectada)
curl "$BASE/instances/$INSTANCE_ID/qrcode" -H "$H1" -H "$H2"

const fs = require("fs");
const BASE = "https://api.zapzapapi.com/api/v1";
const headers = {
  "x-api-key": process.env.ZAPZAP_API_KEY,
  "x-api-secret": process.env.ZAPZAP_API_SECRET,
};

async function main() {
  const id = process.env.INSTANCE_ID;
  const resp = await fetch(BASE + "/instances/" + id + "/qrcode", { headers });
  const corpo = await resp.json();

  if (!resp.ok) {
    console.error("erro", resp.status, corpo.error, corpo.message);
    return;
  }
  if (corpo.connected) {
    console.log("já conectada:", corpo.instance && corpo.instance.status);
    return;
  }
  const qr = corpo.instance && corpo.instance.qrcode;
  if (!qr) {
    console.log("sem QR ainda, tente de novo:", JSON.stringify(corpo));
    return;
  }
  const base64 = qr.replace(/^data:image\/\w+;base64,/, "");
  fs.writeFileSync("qr.png", Buffer.from(base64, "base64"));
  console.log("QR salvo em qr.png, leia com o celular");
}
main();

Tabla de diagnóstico para la llamada del QR. Los mensajes de abajo son los que la API devuelve en el cuerpo de la respuesta.

Dos detalles de integración. El ID de la ruta es el ID de la instancia, no el nombre ni el teléfono. Y el 409 aparece cuando tu código llama al QR en un bucle apretado: la API bloquea la generación por instancia durante un período corto para evitar QR superpuestos. Haz polling con un intervalo de algunos segundos, no en ráfaga.

Primero, revisa que el QR se haya renderizado completo. El campo qrcode es una imagen en base64 y, si tu front recorta el prefijo o usa un elemento de tamaño pequeño, la lectura falla. Muestra la imagen en tamaño grande, con fondo blanco y sin un filtro de modo oscuro que invierta los colores.

Segundo, el celular necesita tener WhatsApp actualizado e internet. Abre Configuración, Dispositivos vinculados, Vincular un dispositivo. Si el celular ya llegó al límite de dispositivos vinculados, quita uno antes. Tercero, QR vencido: genera uno nuevo y léelo enseguida. Si el flujo está en una pantalla tuya, actualiza el QR cada cierto tiempo mientras el status no sea connected.

Si aun así la lectura falla, usa la vinculación por código, que no depende de la cámara.

La llamada conectar instancia acepta el campo phone. Con el teléfono en formato internacional (código de país, código de área y número, solo dígitos), la API genera un código de vinculación en lugar de un QR. En el celular, ve a Dispositivos vinculados, Vincular un dispositivo, y elige vincular con número de teléfono, escribiendo el código mostrado. Sin el campo phone, la llamada genera el QR.

La API valida el formato del teléfono y devuelve un error de validación para números con símbolos o sin código de país. El código llega en instance.paircode en la respuesta. Genera el código solo cuando vayas a usarlo, porque una nueva generación reemplaza a la anterior.

curl -X POST "https://api.zapzapapi.com/api/v1/$INSTANCE_ID/instance/connect" \
  -H "x-api-key: $ZAPZAP_API_KEY" \
  -H "x-api-secret: $ZAPZAP_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"phone":"5511999999999"}'
# digite no celular o código recebido em instance.paircode

Si la lectura del QR funciona pero la instancia vuelve a desconectarse enseguida, el problema ya no es el QR. Mira la guía de WhatsApp que se desconecta solo en la API. Si WhatsApp se niega a vincular el número, puede que esté restringido por el propio WhatsApp; el camino es el de la guía número baneado: qué hacer.

Para crear la instancia y conectar paso a paso, el inicio rápido muestra el flujo completo, y la página de API de WhatsApp lista los endpoints de instancia. El costo por número activo está en precios.

[ ] Creé la instancia y tengo el ID correcto (no el nombre ni el teléfono)

[ ] El status de la instancia no es connected cuando pido el QR

[ ] Hay saldo suficiente y la instancia no está suspendida ni bloqueada

[ ] Hago una llamada de QR a la vez y espero unos segundos entre intentos

[ ] El QR se muestra completo, en tamaño grande y con fondo blanco

[ ] El WhatsApp del celular está actualizado y con internet

[ ] Si la cámara falla, uso la vinculación por código con el teléfono en formato internacional

En interfaces para clientes finales, conviene mostrar instrucciones paso a paso junto al QR (abrir WhatsApp, Dispositivos vinculados, Vincular un dispositivo) y un botón para generar otro QR. Actualiza el QR automáticamente mientras el status no pase a connected y muestra un mensaje claro cuando la API responda 402 o 403, para que el usuario sepa que el problema no es su cámara.