API o panel: qué usa una agencia para gestionar varios números de WhatsApp

Hasta algunas decenas de números, con pocos clientes nuevos al mes, el panel resuelve: crear la instancia, conectar por código QR, activar el calentamiento, armar la IA y el Flow Builder y configurar el portal del cliente. Cada acción toma minutos, y aprendes el producto antes de automatizar. Automatizar demasiado pronto es gastar tiempo de desarrollo en un proceso que todavía va a cambiar.

El panel también es el lugar de todo lo visual y de decisión: armar flujos, ajustar el tono de la IA, mirar conversaciones, configurar la marca del cliente y las secciones del portal. Eso no está en la API de gestión.

La API conviene cuando el mismo trabajo se repite: cada cliente nuevo exige las mismas cinco etapas. Una señal clara es que el onboarding compita con la entrega por el tiempo del equipo. Otra es que ya tengas un sistema propio (CRM, ERP, portal de la agencia) donde nace el cliente, y quieras que la instancia nazca junto con él.

La API de gestión crea, lista, consulta y elimina instancias con clave y secreto, devuelve el costo antes de la creación y permite guardar un campo metadata en la instancia. La documentación de autenticación y la referencia traen todos los campos.

La primera es consultar el costo (GET /instances/cost), para que tu automatización revise el saldo antes de crear. La segunda es crear la instancia (POST /instances) guardando el identificador del cliente y el plan en el metadata. La tercera es registrar el webhook de la instancia (PUT /instances/{id}/webhook), apuntando a tu sistema; cada evento llega con el metadata, así que sabes de quién es.

El ejemplo de abajo une las dos primeras. Guarda la clave y el secreto en variables de entorno, nunca en el código ni en el front-end.

# Create a new client instance and store who the client is in metadata
curl -X POST "https://api.zapzapapi.com/api/v1/instances" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ZAPZAP_API_KEY" \
  -H "x-api-secret: $ZAPZAP_API_SECRET" \
  -d '{"name":"cliente-a-loja-centro","metadata":{"customerId":"cli_123","plan":"basico"}}'

# Before that, to see the activation fee and the balance needed:
curl "https://api.zapzapapi.com/api/v1/instances/cost" \
  -H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET"

Incluso una agencia 100% automatizada vuelve al panel para: escanear el código QR (lo hace el cliente, por el enlace de conexión), configurar la marca del cliente, armar y copiar flujos, ajustar la IA, abrir el portal y seguir las señales de cada número. El diseño que funciona es híbrido: API para lo que se repite, panel para lo que exige criterio.

Para el cliente, el portal es la capa de panel que usa. Entra por enlace o por número y contraseña, ve leads y ventas y reconecta el código QR, sin acceder a tu cuenta. Mira la página de reventa con la marca del cliente.

Etapa 1, hasta unos 10 números: todo por el panel, con la hoja de operación (mira cómo organizar decenas de números). Etapa 2, de 10 a 30: automatiza la creación y el webhook por API, manteniendo el resto en el panel. Etapa 3, por encima de eso: conecta la creación de instancias a tu CRM, recibe los eventos en un único endpoint y sigue la salud de los números en una vista tuya.

En todas las etapas, el costo es el mismo por número: R$15 al mes, sin cobro por mensaje. Mira cuánto cuesta operar 10, 25 o 50 números y la página de agencias.

La automatización crea números rápido, y un número creado demasiado rápido se vuelve un chip usado para envíos masivos demasiado pronto. Pon un freno a la creación en lote: tu automatización debe crear la instancia, pero el inicio de los envíos depende de la fase de calentamiento. Verifica la idempotencia en la creación (no crees dos veces la instancia de un mismo cliente) y registra los errores de saldo insuficiente, que deben alertar a una persona.

Automatizar no reduce el riesgo del canal no oficial. WhatsApp puede limitar o bloquear números, y la API de WhatsApp no cambia eso.