--- name: enriquecer-base description: Arma y enriquece, en cascada, una base de datos de clientes potenciales (B2B) para cualquier industria y país, guiando a la persona paso a paso hasta que tenga una base real, verificada y ordenada para vender. Úsela cuando alguien quiera «armar una base de datos», «conseguir clientes potenciales», «enriquecer mi base», «prospectar», «sacar contactos de empresas», encontrar registros oficiales o datos abiertos de un sector, o pida una lista de negocios con teléfono, sitio web, redes, pauta, tamaño o cualquier señal comercial. Combina registros oficiales, Google (API oficial), Apify y otros proveedores, sitios web y redes. No es para conseguir datos personales de individuos. --- # Enriquecer una base de datos de clientes potenciales Usted va a acompañar a una persona —normalmente el dueño de un negocio o alguien de ventas, **sin formación técnica**— desde «quiero clientes potenciales» hasta un archivo con empresas reales, verificadas, enriquecidas y ordenadas de la que más vale la llamada a la que menos. No le entregue un plan: entréguele el resultado. Esta skill sale de cómo conagentes arma su propia base de hoteles en Colombia: un registro público como punto de partida, enriquecimiento en cascada desde varias fuentes y una base maestra que nunca pierde un dato. Las reglas de abajo vienen de errores reales. ## Si le pegaron este archivo en el chat Ofrézcale a la persona instalarlo como skill, para que quede disponible en cualquier proyecto. Guárdelo tal cual, con el nombre `SKILL.md`, en: - **Claude Code:** `~/.claude/skills/enriquecer-base/SKILL.md` - **Codex:** `~/.agents/skills/enriquecer-base/SKILL.md` Si usa las dos herramientas, guarde una sola copia y enlace la carpeta desde la otra ubicación. Después siga con la entrevista: no hace falta reiniciar nada para empezar. ## La idea en una frase Se parte de una lista pública de empresas (quién existe) y se le agregan columnas por niveles (quién vale la llamada y qué decirle). Cada nivel corre solo sobre las filas que pasaron el anterior, nunca borra nada, y cada dato queda con su fuente y su fecha. ``` Lista inicial registro oficial, datos abiertos, Google, gremios, base propia Nivel 1 ¿Existe y se puede contactar? activa, abierta, teléfono, sitio que carga, correo de la empresa Nivel 2 ¿Qué hace hoy? vende en línea, WhatsApp, píxel, redes activas, pauta, reseñas Nivel 3 ¿Qué tan grande es? ingresos, empleados, habitaciones, contratos con el Estado, sedes Nivel 4 ¿Por qué llamarla? puntaje, categoría A/B/C y la primera frase de la llamada ``` ## Cómo trabaja usted con la persona 1. **Usted guía; la persona decide.** Explique cada paso en lenguaje sencillo, sin jerga («una API es una puerta para que un programa le pida datos a un servicio»). Pregunte una cosa a la vez y proponga una respuesta por defecto, para que pueda decir «sí». 2. **Nada se gasta sin permiso.** Antes de usar un servicio pago, diga cuánto puede costar, para cuántas filas, y espere un sí explícito. 3. **Primero una muestra, después el resto.** Siempre 20 filas antes de cientos. La persona revisa la muestra antes de seguir. 4. **Nunca invente un dato.** Si no se encontró, escriba `no_se_sabe`. Lo que usted infiere se marca como inferido, con su razón. Una base con vacíos honestos vale más que una llena de suposiciones. 5. **Cada dato con su fuente y su fecha.** Si mañana alguien pregunta «¿de dónde salió este teléfono?», la base lo responde. 6. **Lo repetitivo lo hace un programa que usted escribe**, no usted leyendo página por página. Use su criterio (el modelo) para lo que no tiene forma fija: decidir si dos nombres son la misma empresa, clasificar un caso raro, escribir la frase de llamada. 7. **Muestre, no describa.** «Encontré 1.840 empresas; 1.212 tienen sitio web que carga» le sirve más que «el nivel 1 avanzó bien». 8. **Nunca le pida que pegue llaves o contraseñas en el chat.** Indíquele cómo ponerlas en `.env` y léalas desde ahí, sin mostrarlas. 9. **Todo queda en la carpeta del proyecto** y se puede retomar. Si la sesión se corta, otra sesión lee `ESTADO.md` y sigue. 10. **Hable en el idioma de la persona.** En Colombia, de usted. Al empezar, dígale en tres líneas qué van a hacer juntos (entrevista → lista inicial → muestra de 20 → enriquecimiento → base final) y cuánto tiempo de ella necesita: unos 30 minutos de su atención, repartidos; el resto lo hace usted. ## Fase 0 · La entrevista (antes de tocar cualquier dato) Haga estas preguntas, de a una o dos por mensaje. Con las respuestas, escriba `brief.md` (plantilla al final) y muéstreselo para que lo confirme. 1. ¿Qué vende, en una frase? 2. ¿A qué tipo de empresas? (sector, tamaño). Si no sabe, ayúdele: «¿quiénes son sus tres mejores clientes hoy? ¿qué tienen en común?» 3. ¿En qué ciudades o regiones? 4. ¿Qué señal le diría que una empresa **necesita** lo que usted vende? Proponga ejemplos de su sector: «tiene sitio web pero no vende en línea», «está pautando pero no tiene WhatsApp», «abrió hace menos de dos años», «tiene más de 20 empleados», «le vende al Estado», «no publica en redes hace meses». 5. ¿Qué la descarta? (cadenas grandes, cerradas, ya son clientes, competencia). 6. ¿Qué va a hacer con la lista? (llamar, escribir por WhatsApp, visitar, correo). Eso decide qué datos de contacto importan. 7. ¿Cuántas empresas necesita? ¿Para cuándo? ¿Cuántas puede contactar por semana? 8. ¿Presupuesto para datos? Ofrezca tres niveles: **cero** (solo fuentes abiertas y gratuitas), **bajo** (unos pocos dólares: los usos gratis de Apify o de Google), **medio** (USD 20–100 para miles de filas). 9. ¿Ya tiene una base o un Excel de clientes? (sirve para excluir y para aprender cómo se ve un buen cliente). 10. ¿Qué tan cómodo está con la tecnología? (ajusta cuánto explica y cuánto hace usted solo). Con eso, proponga **las señales de los niveles 2 y 3: no más de 6 a 8.** Regla: entra solo la señal que le cambiaría la primera frase de la llamada o la prioridad. Cada columna de más es tiempo de máquina y ruido en la tabla. ## Fase 1 · Preparar el terreno 1. Cree la carpeta del proyecto (si no está ya en una): ``` proyecto-base/ brief.md lo que quiere la persona ESTADO.md en qué paso van, qué falta, decisiones tomadas, costo acumulado fuentes.md cada fuente: qué da, cómo se consultó, costo, términos de uso datos/crudo/ lo que llega de cada fuente, tal cual y con fecha en el nombre (nunca se edita) datos/base.sqlite la base maestra scripts/ los programas que usted escribe salida/ los archivos para la persona (CSV / Excel) .env llaves de servicios (nunca se comparte ni se sube a ningún lado) ``` 2. Revise qué tiene a mano y dígaselo en una lista corta: Python 3 o Node.js (prefiera Python: `requests`, `pandas`, `sqlite3`), acceso a la web desde la terminal, un navegador controlable (un MCP de navegador) y servicios conectados (Apify, Google). Con Python y acceso a la web se hace casi todo; lo demás se agrega cuando haga falta. No instale nada sin decir qué es y para qué. 3. Si va a usar llaves, guárdelas en `.env` y agregue `.env` y `datos/crudo/` a `.gitignore`. 4. Escriba `ESTADO.md` y actualícelo al final de cada fase. Si ya existe, léalo primero y retome desde donde quedó. ## Fase 2 · La lista inicial: ¿de dónde salen las empresas? Hay cuatro caminos. Casi siempre el mejor es combinar el **1** (quién existe) con el **2** (cómo se contacta). Preséntele a la persona las opciones que aplican a su caso, con costo y calidad, y deje que elija. ### Camino 1 · Registros oficiales y datos abiertos (gratis, la base más sólida) Un registro oficial dice **quién existe legalmente**, con un identificador (NIT, RUC, RFC) que sirve para cruzar fuentes y quitar duplicados. Muchos no traen teléfono: eso viene después. **Cómo encontrar el registro de cualquier sector** (hágalo usted; no le pida a la persona que busque): 1. Busque en el catálogo de datos abiertos del país. En Colombia, datos.gov.co corre sobre Socrata: `https://api.us.socrata.com/api/catalog/v1?domains=www.datos.gov.co&q=&only=dataset&limit=20` Pruebe con el sector, con «registro», «directorio», «prestadores», «vigilados», «inscritos» y con el nombre de la superintendencia o del ministerio que vigila el sector. 2. Para cada candidato revise quién lo publica, cuándo se actualizó, cuántas filas tiene y qué columnas trae: `https://www.datos.gov.co/resource/.json?$limit=5`. Descarte lo que lleve más de dos años sin actualizar, salvo que no haya otra cosa (y dígalo). 3. Descargue filtrando del lado del servidor, no todo: - Por partes: `https://www.datos.gov.co/resource/.json?$where=&$order=:id&$limit=50000&$offset=0`, subiendo `$offset`. Sin `$limit` devuelve solo 1.000 filas. - Completo: `https://www.datos.gov.co/api/views//rows.csv?accessType=DOWNLOAD`. - Si van a ser muchas consultas, pida un token de aplicación gratuito de Socrata y mándelo en el encabezado `X-App-Token`, para no recibir errores 429. 4. **Los filtros de texto son exactos y distinguen tildes** (`'TURÍSTICO'` no es `'TURISTICO'`). Antes de filtrar, mire los valores reales con `$select=,count(*)&$group=`. 5. Guarde lo descargado en `datos/crudo/` y anote la fuente en `fuentes.md`. Los datos de datos.gov.co suelen tener licencia CC BY-SA 4.0: cite la fuente. **Registros colombianos que ya sabemos útiles** (identificadores de datos.gov.co verificados en octubre de 2026; si alguno cambió, búsquelo en el catálogo): | Registro | Id | Qué trae | Sirve para | |---|---|---|---| | RUES (Confecámaras) | `c82u-588k` | Millones de matrículas (siempre filtre): razón social, NIT, cámara, estado, último año renovado, organización jurídica, CIIU principal y secundario. **No trae dirección, municipio, teléfono ni correo.** | **Cualquier sector**: filtre por CIIU, cámara, matrícula activa y renovación reciente | | RUES establecimientos | `nb3d-v3n7` | Establecimientos de comercio con el NIT del dueño y su CIIU | Saber cuántos locales tiene una empresa | | Registro Nacional de Turismo (MinCIT, mensual) | `thwd-ivmp` | Prestadores turísticos: teléfono, celular, correo del establecimiento, dirección, habitaciones, empleados. Muchas celdas dicen «Sin dato». | Turismo y hotelería | | REPS (prestadores de salud) | `c36g-9fc2` | Dirección, teléfono y correo por prestador y por sede. Muchos son personas naturales. | Salud | | SECOP II Proveedores Registrados (diario) | `qmzu-gj57` | NIT, teléfono, correo, dirección, municipio, sitio web, si es pyme, tamaño, códigos UNSPSC. Filtre por `tipo_empresa`: hay muchas personas naturales. | Empresas que le venden o quieren venderle al Estado | | SECOP II Contratos | `jbjy-vk9h` | Qué le vende cada proveedor al Estado, por cuánto y cuándo | Señal de tamaño y de actividad | | Supersociedades: las 10.000 empresas más grandes | `6cat-2gcs` | Ingresos, activos, CIIU y ciudad (2021–2025) | Tamaño real | | Supersociedades: estados financieros NIIF | `pfdp-zks5`, `prwj-nzxa` | Estados financieros en formato largo; reorganícelos por NIT | Tamaño y crecimiento | | Supersolidaria: entidades vigiladas | `kg2d-yfyg` | NIT, dirección, correo, actividad | Cooperativas y fondos | | Superfinanciera: entidades vigiladas | `sr9n-792w` | Entidades financieras vigiladas | Sector financiero | | MinEducación: colegios | `cfw5-qzt5` | Establecimientos educativos | Educación básica | | MinEducación: instituciones de educación superior | `n5yy-8nav` | Teléfono y sitio web | Educación superior | | INVIMA (ejemplos) | `ui32-p9f2`, `y4qt-w6tk` | Registros sanitarios: fabricantes y titulares | Alimentos, medicamentos, cosméticos | **Filtrar por actividad (CIIU).** Traduzca lo que dijo la persona («restaurantes», «distribuidores de alimentos») a códigos CIIU y muéstreselos para que confirme. Ojo: el DANE adoptó la **CIIU Rev. 5 A.C.** en agosto de 2026 (Resolución 992), pero el RUES y el RNT siguen usando los códigos de la **Rev. 4 A.C.** Para filtrar esos registros, use la Rev. 4. El RUES también se consulta empresa por empresa en rues.org.co, sin API pública: sirve para verificar casos sueltos, no para descargar. **Fuera de Colombia** (verifique que sigan vigentes): | País | Dónde mirar primero | |---|---| | México | DENUE del INEGI: directorio nacional de establecimientos con nombre, actividad, dirección, teléfono, correo y sitio web; API con token gratuito al registrarse | | Perú | Padrón de RUC de SUNAT (descargable) y datos abiertos del Estado | | Chile, Argentina, Ecuador y otros | El portal de datos abiertos del país, el servicio de impuestos y el registro de comercio | | Reino Unido | Companies House, con API gratuita | | Cualquiera | OpenCorporates agrupa registros mercantiles de muchos países | ### Camino 2 · Google: negocios por categoría y ciudad, con teléfono y sitio web Google Maps es donde más negocios tienen teléfono, sitio web, horario y reseñas. Hay tres formas de usarlo, de la más limpia a la más manual: 1. **API oficial de Google (Places API, versión «New»). Es la forma que Google permite, y la que usted recomienda.** Requiere un proyecto en Google Cloud con facturación activa y una llave (ver «Integraciones»). - **Costo (precios vigentes desde marzo de 2025; confírmelos en la página de precios de Google Maps Platform):** ya no hay crédito de USD 200; cada tipo de consulta tiene su propio uso gratis mensual. Pedir teléfono, sitio web o calificación pone la consulta en el nivel **Enterprise**: 1.000 consultas gratis al mes por tipo de consulta, y después unos USD 35 por cada 1.000 búsquedas de texto y unos USD 20 por cada 1.000 consultas de detalle. Pedir solo nombre, dirección y estado (nivel **Pro**) trae 5.000 gratis. - **Pida solo los campos que necesita** (máscara de campos): la API cobra según los campos. - **Términos de Google:** el `place_id` se puede guardar sin límite; el resto del contenido no se acumula (las coordenadas, máximo 30 días). Por eso: use Places para **encontrar** el sitio web y el teléfono, y guarde como dato el que confirme en el sitio de la propia empresa, con esa fuente. Lo que no se confirme, se vuelve a consultar por `place_id` cuando haga falta. 2. **Apify (actores de Google Maps).** Más fácil para miles de filas y más barato por fila (ver la tabla de Apify). **Dígaselo a la persona sin rodeos: estos actores sacan la información de Google Maps raspando la página, y los términos de Google prohíben extraer su contenido así.** Apify deja la responsabilidad en quien lo usa. La vía que cumple es la API oficial. Si aun así la persona elige este camino, que sea una decisión informada: anótela con fecha en `ESTADO.md`. 3. **Navegador controlado por usted (un MCP de navegador).** Solo para pocas filas, verificaciones puntuales o casos raros. Es lento y no sirve para extraer en masa. Si aparece un captcha o una página de inicio de sesión, pare y avísele a la persona; no lo resuelva ni lo esquive. **Cruzar el registro con Google (lo más delicado de todo el proceso):** - La razón social del registro casi nunca es el nombre comercial («INVERSIONES PÉREZ Y CÍA S.A.S.» es «Hotel La Montaña»). Busque con el nombre, el municipio y, si lo hay, la dirección. - Puntúe la coincidencia de 0 a 1: nombre normalizado (sin «S.A.S.», «LTDA», tildes ni mayúsculas), misma ciudad, dirección parecida. Guarde ese puntaje. - **≥ 0,8:** se acepta. **0,5–0,8:** va a una lista de revisión para la persona. **< 0,5:** no hay coincidencia. - **Las filas sin coincidencia no se borran.** En nuestro piloto, solo entre el 18 % y el 28 % de las empresas del registro (1 de cada 4–5) coincidió con Google con confianza. Esa brecha es un hallazgo: empresas que existen pero que casi nadie está contactando. Pruebe también al revés: buscar por categoría en la zona y cruzar con el registro por NIT, dirección o teléfono. ### Camino 3 · Otras fuentes abiertas - **OpenStreetMap** (API Overpass): negocios por categoría y zona, gratis, licencia abierta (ODbL, con atribución). Cobertura irregular en Colombia, pero sirve para contrastar. - **Gremios, cámaras, ferias y directorios sectoriales** con listados públicos de afiliados o expositores. - **La base propia de la persona**: clientes actuales (para excluir y para aprender el perfil) y contactos viejos. - **Una lista hecha a mano.** Si no hay nada más, 50 empresas escritas a mano también sirven: la cascada funciona igual. ### Camino 4 · Proveedores pagos de datos Mencione que existen (bases compradas, proveedores de correos), pero recomiende no empezar por ahí: la calidad en Colombia es irregular, muchos venden datos personales sin autorización (problema con la Ley 1581) y la persona no aprende de dónde salen sus datos. Si de todos modos quiere, pruebe con 20 empresas de su lista antes de pagar y exija saber de dónde sale cada dato y si hubo autorización. **Punto de control:** muéstrele a la persona las dos o tres mejores fuentes en una tabla (qué cubre, filas, actualización, costo), con su recomendación, y espere el visto bueno. ## Fase 3 · La base maestra Una sola base (SQLite) es la verdad. Todo lo demás —archivos crudos, CSV de salida— sale de ahí o entra ahí. ```sql CREATE TABLE empresas ( id TEXT PRIMARY KEY, -- el place_id de Google si existe; si no, un hash de nit|razon_social|municipio nit TEXT, razon_social TEXT, nombre_comercial TEXT, ciiu TEXT, municipio TEXT, departamento TEXT, direccion TEXT, telefono TEXT, tipo_telefono TEXT, -- fijo | movil | no_se_sabe (formato +57…) correo_empresa TEXT, sitio_web TEXT, sitio_carga INTEGER, google_place_id TEXT, coincidencia REAL, calificacion REAL, resenas INTEGER, estado_negocio TEXT, instagram TEXT, ig_dias_ultima_publicacion INTEGER, pauta_meta_activa INTEGER, pauta_destino TEXT, whatsapp_en_sitio INTEGER, pixel_meta INTEGER, vende_en_linea INTEGER, tamano TEXT, -- la medida que sirva al sector: ingresos, empleados, habitaciones… nivel INTEGER DEFAULT 0, -- hasta qué nivel de la cascada llegó puntaje REAL, categoria TEXT, -- A | B | C | descartada motivo_descarte TEXT, frase_llamada TEXT, actualizado TEXT ); CREATE TABLE fuentes (empresa_id TEXT, campo TEXT, valor TEXT, fuente TEXT, consultado TEXT); ``` Adapte las columnas a las señales de `brief.md`; no agregue columnas que nadie va a usar. **Reglas de la base:** - **Insertar o actualizar por `id`**, nunca duplicar. Cuando una fila del registro se cruza con Google, pasa a usar el `place_id` como `id` y se fusiona con la fila de Google si ya existía. - **Nunca reemplace un dato lleno con un vacío.** Volver a correr un paso no borra lo que ya se sabía. - **Cada valor nuevo deja una fila en `fuentes`.** Ese es el registro de procedencia. - **Normalice al guardar:** teléfonos en formato internacional (+57 y el número; los móviles colombianos empiezan por 3), municipios con su nombre oficial (código DIVIPOLA si la fuente lo trae), sitios web sin parámetros de rastreo, duplicados por NIT. - **Solo las activas**, si la fuente trae estado o año de renovación: una renovación reciente es la mejor señal de que la empresa sigue viva. Diga cuántas filas salieron y por qué. - **Los programas se pueden retomar:** guardan avance cada 25 filas y, al volver a correr, saltan lo que ya está hecho. **Punto de control:** muestre cuántas filas quedaron, cuántas tienen NIT y diez filas de ejemplo. ## Fase 4 · La cascada Para cada nivel, el mismo ciclo: **diseñar → probar con 20 → revisar con la persona → corregir → correr todo.** **Nivel 1 · ¿Existe y se puede contactar?** - Matrícula activa (registro) y negocio abierto (Google: `estado_negocio`). - Sitio web: de la fuente oficial si lo trae; si no, del dominio del correo de la empresa (si no es gmail, hotmail, etc.); si no, de Google Places. - ¿El sitio carga? Respuesta 200, siguiendo redirecciones; que no sea una página de dominio en venta ni un sitio vacío. - Teléfono y correo de la empresa, confirmados en su propio sitio (enlaces `tel:` y `mailto:`, página de contacto, pie de página). - **Filtro:** sin forma de contacto no hay llamada. Esas filas se quedan en la base, marcadas, pero no siguen bajando. **Nivel 2 · ¿Qué hace hoy? (las señales del brief)** Sitio web (gratis, con un programa propio): - Descargue la página de inicio **y** las internas obvias (contacto, reservas, tienda, citas): los motores de reserva y los botones de compra muchas veces solo están adentro. - Señales en el HTML: píxel de Meta (`connect.facebook.net/…/fbevents.js` o `fbq('init'`), Google Tag Manager (`googletagmanager.com/gtm.js`, `GTM-…`), WhatsApp (`wa.me/`, `api.whatsapp.com/send`), redes sociales (enlaces a instagram.com, facebook.com, tiktok.com, linkedin.com: el perfil que la empresa misma enlaza es el bueno), plataformas de tienda o reservas (por su dominio o su script), formulario de contacto, chat. - **Si una señal no aparece en el HTML, no concluya que no existe:** muchos sitios cargan botones con JavaScript después. Para las filas importantes, verifique con un navegador sin interfaz (Playwright) antes de marcar «no tiene». En conagentes, la primera versión del detector dijo que casi ningún hotel tenía reservas en línea; estaba mal por esto. - A veces el «sitio web» de la empresa es una tienda o un motor de reservas de un tercero. Márquelo como tal. Redes y pauta: - **Instagram:** si la empresa enlaza un perfil, guárdelo. Para seguidores y días desde la última publicación, la vía oficial es la «Business Discovery» de la API de Instagram, que exige que la persona tenga una cuenta profesional conectada a una app de Meta: propóngala solo si esa señal es de las más importantes. Para pocas filas, el navegador. Los actores de Apify para Instagram raspan la página, y los términos de Instagram prohíben la recolección automática: dígaselo a la persona antes. - **Biblioteca de anuncios de Meta** (pública): si la empresa tiene anuncios activos, desde cuándo, cuántos y a dónde llevan (WhatsApp, sitio web, Instagram). No muestra cuánto gastan, y los anuncios que ya terminaron desaparecen: anote la fecha de la consulta. - La API oficial de Meta **no** cubre los anuncios comerciales en Colombia: solo los políticos o sociales y los que se muestran en la Unión Europea y el Reino Unido. - Para pocas filas, el navegador en `facebook.com/ads/library`, buscando por el nombre de la página, a ritmo humano. Existe un actor de Apify para muchas filas, pero raspa una página de Meta, cuyos términos prohíben la recolección automática sin permiso: misma advertencia que con Google Maps. Señales propias del sector: pregunte a la persona qué más le cambiaría la conversación (para hoteles: si vende en Booking, qué sistema de reservas usa; para restaurantes: si está en apps de domicilios; para industria: si exporta). **Nivel 3 · ¿Qué tan grande es?** (solo si el brief lo necesita) - El mismo registro (en turismo, habitaciones y empleados; en SECOP, si es pyme y su tamaño). - Estados financieros de Supersociedades: ingresos y activos por NIT. - Contratos con el Estado (SECOP II Contratos): cuántos, de qué monto, de cuándo. - Número de establecimientos (RUES establecimientos) o de sedes en su sitio. - Señales de crecimiento: vacantes en su propio sitio, sedes nuevas, pauta reciente. **Nivel 4 · Puntaje y frase de llamada** - Puntaje simple y explicable, con pesos que la persona entienda y pueda cambiar (`config_puntaje.md`): por ejemplo, +3 si tiene la señal de dolor principal, +2 por tamaño adecuado, +2 si hay teléfono, +1 si está activo en redes, −5 si es cadena o ya es cliente. Nada de cajas negras: la persona tiene que poder leer por qué una empresa quedó arriba. - Categorías: **A** (llamar primero), **B**, **C**, **descartada** (con el motivo). - `frase_llamada`, para las A y B: una frase con **un dato verificado de la base** que la empresa reconozca como suyo. Nunca una frase con un dato que no esté en la base, ni halagos. - Mal: «Le quiero ofrecer un servicio que le va a encantar». - Bien: «Vi que tienen un anuncio activo en Instagram que lleva a WhatsApp desde hace tres semanas: ¿quién le contesta a esa gente el domingo?». ## Fase 5 · La muestra de 20 (obligatoria) 1. Corra todo el proceso sobre 20 filas elegidas al azar (no las primeras: suelen ser las más fáciles), variadas: grandes y pequeñas, con y sin sitio web. 2. Muéstrele a la persona una tabla corta y revisen juntos: - que abra 5 sitios web y compare con lo que dice la tabla; - que los teléfonos y correos sean de la empresa, no de personas; - que cada dato tenga fuente y fecha; - que haya `no_se_sabe` donde debe haberlo (una tabla sin un solo vacío es sospechosa); - que las coincidencias de 0,5–0,8 sean de verdad la misma empresa; - que las frases de llamada usen solo datos de la tabla. 3. Mida columna por columna cuántas de las 20 están bien. Si una columna falla en más de 2, corrija el detector antes de seguir. 4. Reporte: cuántas pasaron cada nivel, cuántas coincidencias con Google, tiempo por fila, costo por fila y la proyección para el total. 5. Cuando la persona señale un error, pídale el ejemplo concreto («la fila 7 dice que no tiene WhatsApp y en su sitio sí hay un botón»), corrija, vuelva a correr sobre las mismas 20 y espere el visto bueno para el resto. ## Fase 6 · La corrida completa - Por lotes (100–500 filas), en segundo plano, retomable. Si va a tardar horas, dígale cuánto. - Pausas aleatorias entre consultas (1–3 segundos por sitio), una consulta a la vez por dominio, un `User-Agent` honesto, y respete `robots.txt`. - Cada lote actualiza `ESTADO.md`: filas hechas, pendientes, errores, costo acumulado por servicio. - Si el costo real se acerca al acordado, pare y pregunte. - Si una fuente empieza a fallar o a bloquear, pare esa fuente; no la fuerce. Esas filas van a revisión manual. ## Fase 7 · La entrega En `salida/`: - `base_completa.csv` (y `.xlsx` si la persona usa Excel): todas las filas, con su categoría y el motivo de las descartadas. - `para_llamar.csv`: solo A y B, ordenadas por puntaje, con teléfono, sitio, señales y `frase_llamada`. - `revisar.csv`: las coincidencias dudosas. - `resumen.md`: cuántas empresas había, cuántas pasaron cada nivel, de qué fuentes salió cada dato, costo total, qué quedó pendiente y cómo actualizar la base en uno o tres meses (los datos envejecen: repita los niveles 1 y 2 solo sobre las activas). Cierre explicándole a la persona, en cinco líneas, qué tiene y qué haría usted primero con la lista. Ofrézcale subirla a su CRM o a una hoja compartida. ## Integraciones paso a paso Guíe estas configuraciones solo cuando la persona eligió usarlas. Ella hace los clics; usted le dice exactamente dónde. Una pantalla a la vez; pida que le confirme cada paso. ### Google Places API (New) 1. Entrar a console.cloud.google.com, crear un proyecto y activar la facturación. Google pide tarjeta aunque haya uso gratuito. 2. En «APIs y servicios», activar **Places API (New)**. 3. En «Credenciales», crear una llave de API y **restringirla** a Places API (New). 4. Poner una alerta de presupuesto de bajo monto en Facturación → Presupuestos y alertas. 5. Guardar la llave en `.env` como `GOOGLE_PLACES_KEY`. 6. En cada consulta, mandar la máscara de campos (`X-Goog-FieldMask`) con solo lo necesario. Por ejemplo: `places.id,places.displayName,places.formattedAddress,places.nationalPhoneNumber,places.websiteUri,places.businessStatus,places.rating,places.userRatingCount`. 7. Hacer la búsqueda de texto con el nombre comercial (o la razón social) más el municipio: `POST https://places.googleapis.com/v1/places:searchText` con `{"textQuery": "Hotel La Montaña, Guatapé, Antioquia"}`. 8. Antes de correr todo, calcule con la persona el costo máximo según el nivel de los campos pedidos y el uso gratis que queda en el mes. ### Apify Apify es una tienda de «actores»: programas listos que recogen datos de un sitio y los devuelven como tabla. Se paga por resultado. **Antes de usar un actor, mire de dónde saca los datos:** si existe una vía oficial (una API, un conjunto de datos abiertos), úsela primero; si el actor raspa un sitio cuyos términos lo prohíben (Google Maps, Instagram, la Biblioteca de anuncios de Meta, LinkedIn, plataformas de reservas), dígaselo a la persona con claridad antes de que decida. 1. **Cuenta.** Que la persona cree una en console.apify.com. El plan gratuito trae USD 5 de uso al mes, que alcanza para la muestra de 20 y algo más. 2. **Token.** En la consola: Settings → **API & Integrations** → copiar el token personal. Guárdelo en `.env` como `APIFY_TOKEN`. 3. **Conexión.** Dos formas: - **Servidor MCP oficial**, en `https://mcp.apify.com`, para buscar y probar actores desde la conversación. - Claude Code: `claude mcp add --transport http apify https://mcp.apify.com --scope user`; luego `/mcp` para iniciar sesión. - Codex: `codex mcp add apify --url https://mcp.apify.com`; luego `codex mcp login apify`. - Para limitar qué actores ve: `https://mcp.apify.com?tools=actors,docs,`. - **Sin MCP:** la API REST de Apify desde un script (o `pip install apify-client`), con el token en el encabezado `Authorization: Bearer`. 4. **Actores útiles.** Precios aproximados por cada 1.000 resultados en octubre de 2026; el plan gratuito paga un poco más. Confirme el precio vigente en la página del actor antes de correr. | Para qué | Actor | Precio aprox. | De dónde saca los datos | |---|---|---|---| | Contactos publicados en los sitios de las propias empresas (correos, teléfonos, redes, WhatsApp) | `vdrmota/contact-info-scraper` | desde USD 1,05 por 1.000 páginas | El sitio de cada empresa: respete su `robots.txt` | | Resultados de búsqueda de Google (por ejemplo, para encontrar el sitio de una empresa) | `apify/google-search-scraper` | desde USD 1,80 por 1.000 páginas de resultados | Raspa Google: términos de Google | | Negocios de Google Maps | `compass/crawler-google-places` | desde USD 1,50 por 1.000 lugares; contactos y detalles aparte | Raspa Google Maps: **los términos de Google lo prohíben; la vía oficial es Places API** | | Google Maps con contactos | `lukaskrivka/google-maps-with-contact-details` | desde USD 2,10 por 1.000 | Ídem | | Biblioteca de anuncios de Meta | `apify/facebook-ads-scraper` | USD 3,40–5,80 por 1.000 anuncios | Raspa Meta: sus términos prohíben la recolección automática sin permiso | | Perfiles públicos de Instagram | `apify/instagram-profile-scraper` | USD 1,60–2,60 por 1.000 perfiles | Raspa Instagram: ídem | 5. **Prueba de costo.** Corra con 10 resultados, revise en la consola cuánto costó de verdad y haga la proyección para el total. Muéstresela a la persona y espere su sí. Ponga un tope de gasto por corrida cuando el actor lo permita. ### Navegador (MCP) Úselo para verificar casos sueltos, leer páginas que cargan con JavaScript y explorar una fuente nueva antes de automatizarla. Opciones: - **Playwright MCP:** - Claude Code: `claude mcp add playwright npx @playwright/mcp@latest` - Codex: `codex mcp add playwright npx "@playwright/mcp@latest"` - **Chrome DevTools MCP:** - Claude Code: `claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest` - Codex: `codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest` - **Claude in Chrome:** la extensión de Chrome, con `claude --chrome`. Usa el navegador real de la persona, con sus sesiones abiertas: más cuidado todavía. No lo use para extraer miles de fichas de un sitio que lo prohíbe. No inicie sesión con las cuentas de la persona y no resuelva captchas. ### Otros servicios que vale la pena conocer - **Firecrawl:** convierte una página, incluso una que carga con JavaScript, en texto limpio. Trae 1.000 créditos gratis al mes. - **SerpApi:** resultados de búsqueda de Google en formato de datos. Trae 250 búsquedas gratis al mes. - **Detectores de tecnología** (qué plataforma usa un sitio): Wappalyzer, de pago, o el proyecto abierto `enthec/webappanalyzer`. - **Buscadores de correos de personas (Hunter, Apollo):** devuelven correos de empleados con nombre propio, y eso es dato personal (Ley 1581). Prefiera los correos genéricos de la empresa (info@, ventas@, reservas@). - **Otras API oficiales:** registros mercantiles con API, el CRM de la persona. Busque « API» y lea la documentación oficial antes de escribir el script. ## Reglas que no se negocian - **Solo información pública.** Nada que exija iniciar sesión con la cuenta de la persona (LinkedIn, Instagram con usuario, grupos privados). - **Términos y robots.txt.** Respételos. Si un sitio prohíbe la extracción automática, use su API oficial o un proveedor autorizado, o deje esas filas para revisión manual. Si la persona decide otra cosa con la información completa, la decisión es suya y queda escrita en `ESTADO.md`. - **Ritmo humano.** Pausas, una consulta a la vez por sitio, nada de saltarse bloqueos ni captchas. - **Datos de empresa sí, datos personales no.** En Colombia, la Superintendencia de Industria y Comercio (concepto 13-230237 de 2013) considera que la Ley 1581 de 2012 protege a las personas naturales, no a las jurídicas: el teléfono y el correo publicados de una empresa no son datos personales. El celular personal del dueño, el correo de un empleado con su nombre o el nombre del representante legal sí lo son: no los recoja ni los use sin autorización. Ojo: muchos negocios pequeños son de una persona natural (RUES, REPS y SECOP tienen muchas filas así); ahí el teléfono publicado del negocio se usa solo para contactar al negocio. - **Antes de contactar (Ley 2300 de 2023, que aplica también entre empresas):** de lunes a viernes de 7:00 a. m. a 7:00 p. m. y sábados de 8:00 a. m. a 3:00 p. m.; nunca domingos ni festivos; no más de un contacto al día ni por varios canales en la misma semana; y una forma fácil de pedir que no lo contacten más. Dígaselo a la persona al entregar la base. - **La base es de la persona.** No la suba a servicios que no eligió, no la comparta y explíquele dónde quedó guardada. - **Usted no es abogado.** Si la persona va a contactar miles de empresas, recomiéndele una consulta legal. ## Problemas comunes | Síntoma | Qué hacer | |---|---| | Muy pocas coincidencias registro → Google | Busque por nombre comercial en vez de razón social; agregue el municipio; cruce al revés (Google → registro por NIT, dirección o teléfono) | | Casi ninguna empresa tiene la señal X, o «no tiene WhatsApp» pero la persona lo ve | El botón carga con JavaScript o está en una página interna: verifique con Playwright o el navegador | | El filtro de datos.gov.co devuelve cero filas | Tildes o mayúsculas distintas: mire los valores reales con `$group` | | Muchos sitios «no cargan» | Siga redirecciones; distinga certificado vencido de sitio caído; pruebe con y sin `www` | | Captchas o bloqueos | Pare esa fuente; baje el ritmo; cambie a la API oficial. No los resuelva | | Tildes y eñes dañadas (ó) | Lea y escriba siempre en UTF-8; al exportar a Excel use UTF-8 con BOM | | Duplicados | Una empresa con varias sedes es varias filas solo si se le vende a cada sede; si no, agrupe por NIT | | El costo se dispara | Pare; revise si está pidiendo campos o resultados de más; vuelva a la muestra | | La sesión se cortó | Lea `ESTADO.md`, revise qué lote quedó a medias y retome: los scripts saltan lo ya hecho | | La persona se pierde | Vuelva a la lista de fases y dígale en una línea dónde van | ## Plantillas `brief.md`: ``` # Brief de la base - Vende: … - Le vende a: … (sector, tamaño) - Dónde: … - Señales de que una empresa lo necesita: … - Lo que la descarta: … - Para qué es la lista: llamar | WhatsApp | visita | correo - Cuántas empresas, para cuándo y cuántas por semana: … - Presupuesto para datos: cero | bajo | medio (tope: USD …) - Base propia para excluir: sí/no (archivo: …) ``` `ESTADO.md`: ``` # Estado - Fase actual: … - Hecho: … - Pendiente: … - Decisiones de la persona: … (fecha) - Fuentes activas y costo acumulado: … - Cómo retomar: … ``` --- Skill gratuita de sebastianconagentes.com. Puede usarla, adaptarla y compartirla.