API de monitorización de la competencia para consultores: una por cliente

En todo contrato de consultoría hay una frase sobre no perder de vista el mercado. Nadie la factura por separado, y es lo primero que se cae en un mes con trabajo.

La versión manual es una pestaña del navegador por cliente y buena memoria. La versión construida es un scraper, que aguanta hasta el tercer encargo. Para entonces, lo que escribiste para el primer cliente lleva meses comparando en silencio una página que se rediseñó en junio, y nadie se ha dado cuenta, porque un monitor que no encuentra nada y un monitor muerto se ven exactamente igual desde fuera.

Una API de monitorización de la competencia para consultores carga con una restricción que no tiene una interna. Vigilas varios mercados a la vez, por cuenta de otros, y exactamente durante lo que dure cada encargo.

Cómo separas la vigilancia de un cliente de la de otro

Un monitor por cliente. Un monitor es un nombre, hasta 20 URLs, una programación cron y una zona horaria, y una cuenta admite 50 de ellos. Eso son cincuenta encargos de veinte páginas cada uno antes de que ningún tope merezca siquiera un pensamiento.

curl -X POST https://crawlforge.dev/api/v1/monitors \
  -H "X-API-Key: cf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Northwind - competitor pricing",
    "targets": [
      { "url": "https://rival-a.com/pricing", "selector": ".pricing-table" },
      { "url": "https://rival-b.com/careers", "selector": "main" }
    ],
    "schedule_cron": "0 7 * * 1",
    "timezone": "Europe/London",
    "retention_days": 365,
    "notify_emails": ["you@yourfirm.com"]
  }'

Ponle el nombre del cliente. No es cuestión de orden: cada comprobación escribe una fila en tu registro de peticiones con ese nombre, el id del monitor y los credits que realmente cobró, así que cuánto gastamos vigilando el mercado de Northwind en agosto pasa a ser una pregunta que el registro responde, en lugar de una que reconstruyes la noche antes de facturar.

Configura también timezone por monitor. El lunes por la mañana del cliente no es necesariamente el tuyo, y una comprobación a las 7:00 en el hemisferio equivocado aterriza después de la llamada a la que tenía que servir.

Puedes manejarlo desde Claude Code en vez de con curl

Sí, y durante la primera semana de un encargo es la mejor herramienta. El MCP server de CrawlForge expone la misma maquinaria a través de track_changes, así que la fase de descubrimiento — ¿qué merece la pena vigilar aquí? — ocurre en el mismo editor en el que ya estás redactando la presentación.

{
  "url": "https://rival-a.com/pricing",
  "operation": "create_scheduled_monitor",
  "trackingOptions": { "customSelectors": [".pricing-table"] },
  "scheduledMonitorOptions": {
    "hosted": true,
    "name": "Northwind - rival A pricing",
    "schedule": "0 7 * * 1"
  }
}

Hay dos cosas de esa llamada que conviene saber antes de apoyarte en ella, y ninguna se deduce del esquema.

hosted viene por defecto en false. Un monitor programado local corre dentro del proceso del MCP server, así que muere en cuanto cierras el editor. Vale para una semana de descubrimiento, no vale para un contrato recurrente. Pon hosted: true y el monitor se muda al scheduler de CrawlForge, donde se dispara esté tu portátil abierto o no.

Un goal en lenguaje natural no sobrevive a la mudanza. En local puedes escribir goal: "tell me when the Pro plan price changes" y un modelo juzga cada diff contra esa frase. Los monitores hosted ignoran goal y notifican cada página cambiada, nueva, bloqueada o con error. La herramienta sí devuelve un aviso diciéndolo, que es fácil de pasar por alto. Acota un monitor hosted con un selector CSS en lugar de con una frase.

Hay además un problema de aritmética, más que una trampa. La ruta MCP crea un monitor por URL, repartiendo customSelectors en destinos sobre esa única página, así que veinte páginas de un cliente por ahí te cuestan veinte de tus cincuenta monitores. El POST REST de arriba mete las veinte en uno solo. Usa MCP la semana en la que estás averiguando qué importa, y luego una llamada REST para el monitor que piensas conservar.

Qué pasa entre fases de un encargo

Lo pausas. Haz PATCH al monitor con status: "paused" y conserva todas las líneas base y se queda sin próxima ejecución, así que no cuesta nada mientras espera. Reanúdalo, y la primera comprobación compara contra la última captura anterior a la pausa. Los meses tranquilos vuelven como un único cambio, no como un agujero en el registro.

Cuando una fase necesita una respuesta hoy y no en la siguiente franja, POST /api/v1/monitors/{id}/run ejecuta una comprobación en el momento y te devuelve las páginas.

De dónde sale realmente el entregable

Del historial de comprobaciones, no de lo que recuerdes. GET /api/v1/monitors/{id}/checks lista las comprobaciones de más nueva a más antigua, y al leer una obtienes sus páginas con change_percent, los recuentos de líneas añadidas y eliminadas, y hasta 20 líneas de muestra de cada lado del diff. Eso es material citable para la diapositiva de qué cambió este trimestre, en vez de una captura que alguien hizo en julio.

Configura retention_days el primer día. Va de 1 a 365 y por defecto son 30, y las comprobaciones más antiguas que la ventana se podan al final de cada ejecución y no vuelven. Un encargo de doce meses que quiera su propio historial al cierre tiene que pedir 365 desde el principio; no hay forma de pedirlo en el mes once. La referencia del endpoint está en la documentación.

Cuánto cuesta vigilar el mercado de un cliente

Tres credits por destino descargado y comparado, el precio de track_changes, venga la llamada de REST o de MCP. Los destinos bloqueados o con error no se cobran. Crear, actualizar, pausar y borrar monitores es gratis.

Veinte páginas con programación de los lunes son cuatro o cinco comprobaciones en una ventana de 30 días, o sea de 240 a 300 credits. Diez clientes con ese patrón se quedan por debajo de 3.000 credits al mes entre todos. No hay usuarios de pago ni tope de cuántas páginas puedes vigilar, que es otro post.

La consecuencia que conviene aplicar es que la amplitud sale barata y la frecuencia no, así que vigila más páginas menos a menudo. Que un rival publique discretamente una vacante de comercial en Múnich en su página de empleo te dice más sobre sus dos próximos trimestres que su página de precios, y esa página cambia como mucho dos veces al año.

Lo que no va a hacer

• No hay vista para el cliente. Una cuenta, una clave, sin acceso por cliente y sin frontera entre monitores. Lo que ve el cliente es lo que tú le mandas.
• No tiene datos de contacto ni firmográficos. Lee las páginas que le indiques, por encima de la base de datos sobre la que ya trabaje tu investigación. No es un Apollo ni un ZoomInfo, y no pretende serlo.
• robots.txt se respeta siempre, sin excepción. Una ruta no permitida devuelve ROBOTS_DISALLOWED en cada comprobación y nunca se cobra.
• Mínimo cinco minutos entre ejecuciones, lo que lo convierte en un instrumento diario y semanal. Que es, de todos modos, el ritmo de un informe.

Si lo que quieres es que el cambio acabe en un CRM o en un canal en lugar de en un documento, el lado del webhook está aquí.

Empieza gratis con 1.000 credits, unos dos meses de la vigilancia diaria de cinco páginas de un cliente, o abre el panel de monitores y lee una comprobación real antes de escribir una sola línea de código.