CDCStream/skills

Diff semanal de bibliotecas de anuncios

Extrae los anuncios visibles actualmente de cada competidor desde las bibliotecas públicas de anuncios, compáralos con la instantánea de la semana pasada y escribe un breve informe de lo que es nuevo, lo que se detuvo y lo que dicen los nuevos anuncios.

Lo que las bibliotecas públicas de anuncios pueden y no pueden decirte

Indica estos límites en cada informe. No permitas que el lector infiera más.

• Las bibliotecas públicas de anuncios no muestran gasto, impresiones ni conversiones para anuncios comerciales comunes. Google publica rangos de gasto e impresiones solo para anuncios electorales; Meta muestra desgloses de alcance solo para algunos anuncios políticos y dirigidos a la UE; LinkedIn muestra impresiones y segmentación en un subconjunto de anuncios. Nunca estimes presupuesto o rendimiento a partir del número de anuncios.
• "No está en la biblioteca" no significa "no está publicitando": las bibliotecas tienen alcance por país y pueden tener un retraso de un día o más.
• La biblioteca de TikTok solo cubre anuncios mostrados en la UE/EEE, el Reino Unido y Suiza. Fuera de esos países, indica "TikTok: no cubierto" — no reportes cero anuncios.
• Las fechas de primera/última visualización de un anuncio son días calendario, no horas exactas.

Entradas a recopilar primero

1. Competidores: nombre de la marca y, si se conoce, su URL de página de Meta, nombre de anunciante de Google y nombre de empresa de LinkedIn.
2. Países (códigos de dos letras). Por defecto: US. Añade un país de la UE/Reino Unido como GB o DE si TikTok es relevante.
3. Ruta del archivo de instantánea. Por defecto: ad-library-snapshot.json en el directorio de trabajo.
4. Si extraer detalles y copia de los anuncios nuevos (más créditos, mejor informe).

Estimado de créditos — mostrar antes de ejecutar

Por competidor, por país:

Paso	Endpoint	Créditos
Encontrar página de Meta	/v1/ad-library/facebook/search-companies	2
Anuncios de Meta	/v1/ad-library/facebook/company-ads	2
Encontrar anunciante de Google	/v1/ad-library/google/advertiser-search	1
Anuncios de Google	/v1/ad-library/google/company-ads	2
Anuncios de LinkedIn	/v1/ad-library/linkedin/search-ads	2
Anuncios de TikTok (solo UE/EEE/Reino Unido/CH)	/v1/ad-library/tiktok/search	2 (hasta 5 en su ruta alternativa)

Eso suma aproximadamente 11 créditos por competidor por país (9 donde TikTok no está cubierto). Los pasos de búsqueda se pueden omitir en ejecuciones posteriores guardando el ID de página y el ID de anunciante en la instantánea.

Opcional, solo por nuevo anuncio: detalles (.../ad-details, 2 cada uno) y copia de anuncio de Meta (/v1/ad-library/facebook/ad-transcript, 2 cada uno). Limítalos — por ejemplo a 5 anuncios nuevos por competidor — e indícalo en el estimado.

Imprime el estimado (competidores × países × 11, más el límite de detalles) y verifica el saldo con GET /v1/account/balance (gratuito). Pide al usuario que confirme antes de gastar.

Cómo llamar a Captapi

Cualquiera de las dos rutas funciona; usa la que esté disponible en el entorno.

• MCP: herramientas nombradas según el endpoint, por ejemplo facebook_ad_library_company_ads, google_ad_library_company_ads, linkedin_ad_library_search_ads, tiktok_ad_library_search.
• REST: GET https://api.captapi.com<path>?<params> con el encabezado Authorization: Bearer $CAPTAPI_API_KEY.

Las llamadas fallidas cuestan 0 créditos. Un error con retryable: true se puede reintentar una vez después de una breve espera; retryable: false es una respuesta definitiva — regístralo, no hagas bucle.

Pasos

1. Carga la instantánea si existe. Mapea competidor → país → biblioteca → {ids: [...], meta: {...}} más los IDs de búsqueda guardados.
2. Resuelve IDs solo donde la instantánea no tenga ninguno:
   • Meta: facebook/search-companies?q=<marca>&country=<cc> → elige la página que coincida con el nombre; guarda su pageId. Si varias parecen correctas, pregunta.
   • Google: google/advertiser-search?q=<marca>&country=<cc> → guarda el ID de anunciante del resultado coincidente.
3. Extrae los anuncios actuales para cada competidor y país:
   • facebook/company-ads?url=<pageId o URL de página>&country=<cc>&status=active
   • google/company-ads?advertiser=<id o nombre de anunciante>&country=<cc>
   • linkedin/search-ads?company=<nombre>&country=<cc>
   • tiktok/search?q=<marca>&country=<cc> — solo para UE/EEE/Reino Unido/CH.
4. Compara por ID de anuncio con la instantánea: nuevo (ahora, no antes), detenido (antes, no ahora), en curso.
5. Enriquece los anuncios nuevos hasta el límite acordado: .../ad-details para fechas y medios, facebook/ad-transcript para titular/cuerpo/CTA/URL de destino de Meta.
6. Escribe el informe (formato a continuación) y guarda la nueva instantánea — solo después de escribir el informe, para que una ejecución fallida nunca sobrescriba la semana pasada.

Formato del informe

Para cada competidor:

• Una línea por biblioteca: nuevo N · detenido N · en curso N, o la razón por la que falta (no cubierto en este país, búsqueda fallida, 0 anuncios encontrados).
• Anuncios nuevos: titular o primera línea de copia, formato (imagen/video/carrusel), fecha de primera visualización, dominio de destino y el endpoint del que provienen, por ejemplo (fuente: /v1/ad-library/facebook/company-ads).
• Temas: 2–4 viñetas sobre los enfoques que comparten los anuncios nuevos (oferta, audiencia, producto). Marca cada uno como [necesita revisión humana] — es una interpretación.
• Anuncios detenidos: recuento, más el que más tiempo estuvo activo y se detuvo.

Termina con la sección de límites anterior, un total de créditos de la ejecución en una línea y la ruta de la instantánea.

Dónde un humano debe revisar

• Qué página o anunciante es "el" competidor cuando la búsqueda devuelve varios.
• Cada afirmación de tema o estrategia — las bibliotecas muestran creativos, no intención.
• Cualquier conclusión sobre presupuesto o rendimiento: no hay datos para ello; el informe debe decirlo en lugar de adivinar.