Cómo armar un panel de leads de anuncios por cliente con Claude Code

Cuatro piezas: un endpoint que recibe el webhook de las instancias, una tabla que vincula cada instancia con un cliente, una tabla de leads con estado y valor, y una página con la consulta por cliente. Los eventos vienen de ZapZap, la venta vuelve por tracking/conversion, y el panel solo lee tu base. Evita dejar que el agente de código consulte la API en cada acceso a la página.

Para la recepción segura, sigue la guía de webhooks idempotentes. Para la medición, mira medir CPL con la API de conversión. Aquí el foco es orquestar al agente.

Empieza por el archivo de instrucciones del proyecto, con la URL base, los nombres de las variables y la regla de usar solo operaciones de la OpenAPI. Luego instala el servidor MCP. El 11/11/2026 el paquete zapzap-mcp no aparece en npm (npm view devolvió 404), así que la instalación es clonando el repositorio github.com/zapzapapi/zapzap-mcp y compilando. Reconfirma con npm view antes de usar npx.

Regístralo con ZAPZAP_READ_ONLY=true, que expone solo las herramientas de lectura (listar instancias, ver estado, consultar mensajes y webhooks). Así el agente consulta y no envía un mensaje por error. El servidor no recibe mensajes: la recepción es el webhook del paso siguiente.

# CLAUDE.md of the dashboard project (instructions for the agent)
- Stack: Node.js + Express + SQLite (or Postgres) + one HTML page.
- ZapZap API: base https://api.zapzapapi.com/api/v1, headers x-api-key and x-api-secret,
  read from ZAPZAP_API_KEY and ZAPZAP_API_SECRET. Never print or commit them.
- Spec: https://zapzapapi.com/openapi/zapzap-openapi.pt.json  Summary: https://zapzapapi.com/llms.txt
- Use only operations present in the spec. If something does not exist, say so.
- The zapzap MCP server is READ ONLY (ZAPZAP_READ_ONLY=true). Never ask to send messages.
- Webhooks: validate X-ZapZap-Signature on the raw body, dedupe by event_id or delivery_id.

# The zapzap-mcp package is not on npm yet (npm view zapzap-mcp returned 404 on 2026-11-11),
# so install from the repository. Check "npm view zapzap-mcp" again before using npx.
git clone https://github.com/zapzapapi/zapzap-mcp.git
cd zapzap-mcp && npm install && npm run build

# Register it in Claude Code in read-only mode (no send tools are exposed)
claude mcp add zapzap \
  -e ZAPZAP_API_KEY=your-api-key -e ZAPZAP_API_SECRET=your-api-secret -e ZAPZAP_READ_ONLY=true \
  -- node /full/path/to/zapzap-mcp/dist/src/index.js

Pide al agente el esquema de abajo, que mapea instance_id a un cliente (la clave que el evento siempre trae) y guarda el lead por teléfono. Mapear por el instance_id del sobre es más robusto que depender de campos extra. El metadata de la instancia sirve como verificación cruzada. La consulta del final alimenta la página.

-- Minimal schema for the per-client lead dashboard
CREATE TABLE clients (id text PRIMARY KEY, name text NOT NULL);
CREATE TABLE instances (instance_id text PRIMARY KEY, client_id text NOT NULL REFERENCES clients(id));
CREATE TABLE leads (
  id integer PRIMARY KEY AUTOINCREMENT,
  client_id text NOT NULL, instance_id text NOT NULL,
  phone text NOT NULL, first_message text, first_seen_at text NOT NULL,
  status text NOT NULL DEFAULT 'open',          -- open | qualified | scheduled | won
  sale_value real, UNIQUE (instance_id, phone));
CREATE TABLE webhook_events (
  instance_id text NOT NULL, dedupe_key text NOT NULL, received_at text NOT NULL,
  PRIMARY KEY (instance_id, dedupe_key));

-- The page query: leads by client in the last 30 days
SELECT c.name, COUNT(*) AS leads,
       SUM(l.status = 'won') AS sales, COALESCE(SUM(l.sale_value), 0) AS revenue
FROM leads l JOIN clients c ON c.id = l.client_id
WHERE l.first_seen_at >= date('now', '-30 days')
GROUP BY c.id ORDER BY leads DESC;

Prompt 1: "Crea el endpoint POST /webhook con express.raw, valida X-ZapZap-Signature (HMAC SHA-256 sobre t.cuerpo, tolerancia de 5 minutos), guarda la clave event_id o delivery_id en webhook_events y responde 200. Escribe pruebas para firma válida, vencida y alterada." Prompt 2: "Usa el MCP para listar las instancias y llenar la tabla instances; muéstrame lo que vas a guardar antes de guardar." Prompt 3: "Registra cada primer mensaje recibido como lead, único por instancia y teléfono. Antes de modelar, guarda el primer payload real y muéstramelo." Ese último pedido evita que el agente invente la forma del campo data.

Prompt 4: "Crea la página /clientes con la consulta, ordenada por leads, y una columna de estado de la instancia." Prompt 5: "Llama a POST /{instanceId}/tracking/conversion cuando yo marque una venta en el panel y trata 404 y 409 como está documentado." En cada paso, exige que el agente cite la operación de la OpenAPI usada.

Revisa tres cosas antes de publicar: secretos solo en variables de entorno, nunca en el repositorio ni en el prompt; texto de cliente final tratado como entrada no confiable (el MCP lee mensajes y pueden contener instrucciones); y un login en la página, porque muestra teléfonos. Mantén el modo solo lectura, y solo piensa en habilitar envío después de un tope de volumen y una lista permitida.

Evoluciona en orden: panel de salud de los números, luego reporte mensual (automatizar reportes), luego el enlace del portal del cliente. Para el contexto general, mira la página de agentes de IA y agencias con IA.