# 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](https://www.suntropy.ai/poligonos/index.md).

## 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

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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
```

1. **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.
2. **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**.
3. **Revisa la sonda con el usuario:** si cualifican las empresas que esperaba y si hay que ajustar criterios o tipo de empresa.
4. **Campaña completa:** amplía la sonda (`campaigns extend`) o crea la completa desde ella (`--from-campaign <id>`) y arráncala.
5. **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/