LeadGen para agentes de IA: cuenta, CLI, skills y primera campaña

Guía para agentes (Claude, ChatGPT, Codex, n8n o el tuyo propio) que quieran encontrar empresas a las que venderles autoconsumo solar con LeadGen, el buscador B2B de Suntropy. Todo se hace desde la terminal, con la CLI de Suntropy y sus skills. El usuario sólo interviene donde hace falta una persona: crear su cuenta, darte una clave y aprobar el gasto.

Qué hace LeadGen

LeadGen busca empresas en una zona de España (un polígono, un municipio o un radio alrededor de un punto) y las cualifica con un pipeline de pasos:

Cubierta: parcela catastral, superficie y potencia fotovoltaica estimada.
Paneles: si ya los tiene y desde qué año (ortofotos actuales e históricas del PNOA).
Datos de empresa: actividad y CNAE, CIF, facturación y empleados.
Contacto: LinkedIn de la empresa y decisores.
Consumo: consumo eléctrico estimado.
Cualificación: según los criterios que defina el usuario.

El resultado es una tabla exportable (CSV) con cada empresa y su ficha.

Ejemplos de lo que produce: páginas por polígono industrial.

Lo que necesitas del usuario

Paso	Quién	Qué
Cuenta de Suntropy	Usuario, 1 minuto	Alta en https://app.suntropy.ai/signup?utm_source=ia-agente&utm_medium=ia con su email y el código que le llega por correo. Si ya tiene cuenta, se salta
Clave para la CLI	Usuario, 30 segundos	Una API key creada en https://app.suntropy.ai/configuration/automations, que te pega en el chat
Acceso a LeadGen	Tú lo pides; Suntropy lo activa	El email de la cuenta y un teléfono de contacto del usuario
Gasto de créditos	Usuario lo aprueba	Antes de arrancar cada campaña, enséñale el coste estimado y espera su «sí»

Todo lo demás lo haces tú:

instalar la CLI;
leer las skills;
diseñar la búsqueda;
lanzar una sonda;
lanzar la campaña completa;
exportar los resultados.

1 · Instala la CLI y las skills

npm install -g @enerlence/suntropy-cli      # o: npx @enerlence/suntropy-cli <comando>
suntropy --version

# Skills: la versión al día está en su repo (fuente única)
git clone --depth 1 https://github.com/enerlence/suntropy-cli-skills /tmp/suntropy-cli-skills
cp -r /tmp/suntropy-cli-skills/skills ~/.claude/skills/suntropy-cli     # Claude Code; otros agentes: .agents/skills/suntropy-cli

Sin git, el paquete trae una copia tomada del repo al publicarse, en $(npm root -g)/@enerlence/suntropy-cli/skills/; skills/.origen dice de qué versión es. SKILL.md es el índice. Lee las de LeadGen antes de crear nada:

Skill	Para qué
`satvolt-cli.md`	Referencia de los comandos de `suntropy satvolt`
`satvolt-campaign.md`	Crear, configurar y explotar una campaña
`satvolt-probe-to-full-campaign.md`	Sonda de pocos leads, revisión y paso a la campaña completa (el flujo recomendado)
`satvolt-lead-troubleshooting.md`	Qué hacer con leads fallidos o resultados raros
`satvolt-api.md`	La API HTTP, por si no puedes usar la CLI
`satvolt-france.md`	Campañas en Francia: SIRET y NAF del registro oficial y consumo real, en lugar de los pasos de España

Skills: https://github.com/enerlence/suntropy-cli-skills · CLI: https://github.com/enerlence/suntropy-cli · paquete: https://www.npmjs.com/package/@enerlence/suntropy-cli

2 · Autentica la CLI

Con la API key que te ha dado el usuario:

suntropy auth set-key --key "$SUNTROPY_API_KEY"   # o exporta SUNTROPY_API_KEY
suntropy auth status

Pide una clave por agente o por equipo, con un nombre que la identifique, para que el usuario pueda revocarla sin afectar a nada más. No la guardes en ficheros que se compartan ni la repitas en el chat.

Nunca pidas ni escribas la contraseña del usuario, tampoco con suntropy auth login. Si no puede crear una API key, díselo y que nos escriba a hola@suntropy.ai.

3 · Pide el acceso a LeadGen

Hoy LeadGen se activa bajo solicitud. Comprueba primero si la cuenta ya lo tiene:

suntropy satvolt templates list --format human

Hay dos respuestas que significan «todavía sin acceso»:

SATVOLT_NOT_ENABLED (401);
ACCESS_CHECK_UNAVAILABLE (503) en una cuenta recién creada. Hoy LeadGen da ese error a las cuentas que aún no tiene dadas de alta. En ese caso no reintentes en bucle: pide el acceso.

Si no lo tiene, pide el acceso con el email de la cuenta y el teléfono del usuario. Antes, pídele permiso para enviarlo:

curl -s -X POST https://www.suntropy.ai/api/leadgen-acceso \
  -H 'Content-Type: application/json' \
  -d '{"email":"<email de la cuenta>","phone":"<teléfono>","utm_source":"ia-agente","utm_medium":"ia"}'

Una persona de Suntropy lo activa, normalmente en horario laboral, y la cuenta recibe 2.000 créditos de bienvenida. Mientras tanto, prepara la búsqueda con el usuario. Cuando templates list responda sin error, sigue.

4 · Diseña la búsqueda con el usuario

Pregúntale tres cosas:

Zona: un polígono, un municipio o un punto con radio.
Tipo de empresa: por ejemplo, «fábrica», «nave industrial», «industria alimentaria» o «logística».
Qué hace que una empresa le interese: superficie mínima, que no tenga paneles, o que los tenga desde hace más de seis años para venderle baterías o ampliación.

Decide si es un barrido por categoría (zona acotada, --business-groups) o una búsqueda por actividad (--search-query, zona que puede ser grande); los criterios están en satvolt-campaign, «Paso 0b». Si la zona está en Francia, usa satvolt-france.

suntropy geocode resuelve una dirección en coordenadas, y suntropy satvolt catalog actions da los pasos disponibles, lo que cuesta cada uno y su configuración.

Antes de gastar nada, estima. campaigns estimate cuenta cuántos negocios encontraría la campaña y enseña una muestra, sin crearla ni gastar créditos:

suntropy satvolt campaigns estimate --circle 27.864,-15.401 --radius 8000 \
  --business-groups businesses --sample 30 --format human

Enséñale la muestra al usuario e itera los grupos o la consulta hasta que se parezca a lo que busca. places.atLeast es un mínimo; si es 0, no crees la campaña.

5 · Sonda, coste y campaña completa

Sigue satvolt-probe-to-full-campaign.md. La sonda es una campaña de pocos leads (5-10) en la zona y con los pasos elegidos; por ejemplo:

suntropy satvolt campaigns create --name "Arinaga · naves (sonda)" \
  --circle 27.864,-15.401 --radius 8000 --search-query "nave industrial" \
  --max-leads 5 --steps @pasos.json

Sonda: créala como en el ejemplo, con la zona y los filtros que validaste en estimate y los pasos que sacas de catalog actions y de la skill.
Coste: la respuesta trae estimatedCreditsPerLead (un máximo: los filtros lo reducen). Calcula el coste máximo de la campaña completa en créditos (estimatedCreditsPerLead × leads), enséñaselo al usuario y no arranques sin su confirmación.
Revisa la sonda con el usuario: si cualifican las empresas que esperaba y si hay que ajustar criterios o tipo de empresa.
Campaña completa: amplía la sonda (campaigns extend) o crea la completa desde ella (--from-campaign <id>) y arráncala.
Resultados: consulta el avance con campaigns get y los leads con leads list, y exporta la tabla con export-tables.

Si algo falla, usa satvolt-lead-troubleshooting.md.

Reglas

El alta y el acceso los aprueba siempre el usuario. Pregúntale antes de completar un alta, pedir acceso o conceder permisos en su nombre, y nunca pidas, escribas ni guardes sus credenciales (contraseña o códigos de verificación). El alta se hace en el navegador; tú le das el enlace.
Nunca arranques ni reanudes una campaña sin enseñar el coste y tener el «sí» del usuario.
Los decisores son datos personales: úsalos sólo para el contacto comercial que pida el usuario, no los publiques ni los compartas con terceros.
Todo queda acotado a la cuenta de la clave: no puedes ver campañas de otras empresas.
Habla en créditos. El coste se enseña y se confirma en créditos; el precio de lista es de 5 € por cada 1.000. Más créditos, desde la tienda de la app.
Cubierta con FIND_ROOFTOP, nunca ROOFTOP_LIDAR: el LiDAR no está disponible.

Contacto

hola@suntropy.ai · https://www.suntropy.ai/leadgen/

Esta guía en Markdown