Verifica el perfil de IG con el brief de campaña antes del lanzamiento: validación mediante API

Antes de lanzar una campaña, puedes cotejar automáticamente una lista de cuentas de IG con el brief y obtener un CSV con solo las filas que requieren atención. Para cada fila, el script consulta el perfil, compara el nombre de usuario, el estado de privacidad y la verificación con los valores esperados, y también guarda los contadores disponibles. Así, una comprobación manual repetitiva se convierte en un paso de control claro antes de poner la campaña en marcha.

El objetivo: detectar discrepancias antes de publicar

La hoja de una campaña suele incluir el nombre de la cuenta y algunas expectativas: el perfil debe ser público, el nombre de usuario debe coincidir con el acordado y la marca de verificación debe corresponder a lo que figura en el brief. Entre la preparación de la lista y el lanzamiento, una cuenta puede cambiar de nombre, hacerse privada o resultar ser otro perfil con un nombre parecido. Si compruebas las filas manualmente, cuesta repetir el proceso y localizar rápidamente las excepciones.

Para este diagnóstico preliminar basta con obtener el perfil mediante el nombre de usuario. La documentación publicada de jsonscraper indica la ruta GET /v1/user/by/username con el parámetro username; también hay un parámetro opcional, cache_timeout. La respuesta puede incluir el nombre de usuario, el nombre completo, los indicadores de privacidad y verificación, la cantidad de publicaciones, seguidores y seguidos, además de la biografía. Hay que leer los campos concretos de la respuesta real: una instantánea del esquema confirma que estaban presentes en la respuesta observada, pero sus valores pueden variar o no estar disponibles.

Prepara la hoja y las reglas de comprobación

Crea un CSV llamado profiles.csv con las columnas username, expected_private y expected_verified. En estas dos últimas, indica los valores esperados true o false, y escribe el nombre de usuario sin el símbolo @. Si no conoces la expectativa para algún perfil, deja la celda vacía: el script no debe tratar la falta de una expectativa como un error.

username,expected_private,expected_verified
examplebrand,false,true
anotheraccount,false,false

La comprobación resuelve dos cuestiones concretas: determina si el nombre de usuario obtenido coincide con el solicitado y detecta diferencias respecto a las expectativas registradas sobre privacidad y verificación. Los contadores y la biografía se guardan como contexto para una evaluación manual; no se consideran pruebas de la calidad de la audiencia ni de la idoneidad del creador para la campaña.

Conecta IG Scraper API

Guarda la clave de acceso en la variable de entorno JSONSCRAPER_INSTAGRAM_LICENSE_KEY. No incluyas el secreto en el CSV, el código fuente ni los registros de ejecución. La documentación oficial del endpoint de IG describe la ruta y los nombres de los parámetros; la dirección base de la API es https://ig.jsonscraper.com y el nombre del parámetro para la clave es license_key.

Antes de procesar toda la lista, realiza una llamada de prueba para una fila de prueba, comprueba la estructura del JSON y confirma que tu cuenta tiene acceso. Como el endpoint acepta un nombre de usuario, no hacen falta un identificador de perfil conocido ni rutas adicionales para este caso sencillo.

Ejemplo: solicitudes, comparación y CSV de excepciones

El siguiente script es compatible con Python 3.8 o posterior. Lee un CSV, realiza una solicitud GET por perfil, comprueba el estado de la respuesta externa y guarda los campos relevantes originales junto con el resultado de la comparación. Instala la dependencia con python -m pip install requests y exporta la clave antes de ejecutarlo.

import csv
import os
import time
from pathlib import Path

import requests

BASE_URL = "https://ig.jsonscraper.com/v1/user/by/username"
API_KEY = os.environ["JSONSCRAPER_INSTAGRAM_LICENSE_KEY"]
INPUT_FILE = Path("profiles.csv")
OUTPUT_FILE = Path("preflight_results.csv")


def parse_expected(value):
    value = (value or "").strip().lower()
    if value == "true":
        return True
    if value == "false":
        return False
    return None


def profile_from_response(payload):
    # The documented observed response wraps profile fields in "ig".
    if payload.get("status") != "ok":
        raise ValueError("API response status is not ok")
    profile = payload.get("ig")
    if not isinstance(profile, dict):
        raise ValueError("Response has no profile object under 'ig'")
    return profile


with INPUT_FILE.open(newline="", encoding="utf-8") as source:
    rows = list(csv.DictReader(source))

results = []
for row in rows:
    requested = (row.get("username") or "").strip().lstrip("@")
    if not requested:
        results.append({
            "requested_username": "",
            "result": "missing_username",
            "error": "username is empty",
        })
        continue

    try:
        response = requests.get(
            BASE_URL,
            params={"username": requested, "license_key": API_KEY},
            timeout=30,
        )
        response.raise_for_status()
        profile = profile_from_response(response.json())

        actual_username = profile.get("username")
        actual_private = profile.get("is_private")
        actual_verified = profile.get("is_verified")
        expected_private = parse_expected(row.get("expected_private"))
        expected_verified = parse_expected(row.get("expected_verified"))

        checks = []
        if actual_username and actual_username.casefold() != requested.casefold():
            checks.append("username_mismatch")
        if expected_private is not None and actual_private != expected_private:
            checks.append("privacy_mismatch")
        if expected_verified is not None and actual_verified != expected_verified:
            checks.append("verification_mismatch")

        results.append({
            "requested_username": requested,
            "username": actual_username,
            "full_name": profile.get("full_name"),
            "is_private": actual_private,
            "is_verified": actual_verified,
            "media_count": profile.get("media_count"),
            "follower_count": profile.get("follower_count"),
            "following_count": profile.get("following_count"),
            "result": "review" if checks else "matched",
            "checks": ";".join(checks),
            "error": "",
        })
    except (requests.RequestException, ValueError, KeyError) as exc:
        results.append({
            "requested_username": requested,
            "result": "request_or_response_error",
            "error": str(exc),
        })

    # A small delay spaces requests; it is not a documented quota guarantee.
    time.sleep(0.5)

fieldnames = sorted({key for item in results for key in item})
with OUTPUT_FILE.open("w", newline="", encoding="utf-8") as destination:
    writer = csv.DictWriter(destination, fieldnames=fieldnames)
    writer.writeheader()
    writer.writerows(results)

print("Saved", len(results), "rows to", OUTPUT_FILE)

El código comprueba la estructura observada de la respuesta: el status externo y el objeto del perfil ig. Si el proveedor cambia el formato, la comprobación de la estructura detendrá el procesamiento de esa fila y guardará un error, en lugar de registrar silenciosamente una coincidencia incorrecta. El script no imprime la clave ni la incluye en el archivo de resultados.

Cómo interpretar el resultado

En preflight_results.csv, las filas con el estado matched han superado las comparaciones definidas. El valor review significa que uno o varios parámetros difieren del brief; la columna checks indica cuáles. Los errores de solicitud o respuesta se marcan por separado, de modo que la falta de acceso a los datos no parece una coincidencia confirmada.

La cantidad de seguidores y publicaciones permite ver junto a la solicitud una instantánea actual del perfil. Son valores puntuales de la respuesta a la solicitud. Para evaluar los cambios a lo largo del tiempo, guarda ejecuciones fechadas por separado; una sola comprobación no contiene un historial. Algunos campos pueden estar vacíos. En ese caso, la fila sigue sirviendo para comprobar la identidad y los demás atributos disponibles, pero no para comparar un contador ausente.

Automatización antes del lanzamiento de la campaña

Después de comprobar manualmente un CSV de prueba, añade el script a una tarea programada o a un paso de preparación de la campaña. Para que el control sea reproducible, guarda la lista original por separado, registra la fecha de ejecución y almacena el CSV de resultados en un repositorio de trabajo privado. Si el nombre de usuario puede cambiar, conviene utilizar un identificador de fila estable de tu sistema para repetir el procesamiento.

Cuando la lista crezca, añade un límite de concurrencia, reintentos únicamente para errores de red temporales y un registro independiente de códigos de error que no incluya secretos. No repitas sin límite las solicitudes con una clave no válida o un nombre de usuario incorrecto. Añade cache_timeout solo si se ajusta a la política de actualidad necesaria: la documentación indica que la caché de IG está desactivada de forma predeterminada y que un valor superior a cero la activa durante el periodo indicado.

La comprobación del perfil reduce la revisión manual a una lista concreta de excepciones: el nombre, la privacidad, la verificación y los contadores disponibles quedan en una sola tabla antes del inicio de la campaña. Para consultar los parámetros de la API y las opciones de integración actuales, utiliza la página de IG Scraper API y la documentación de las rutas.