Compare perfis do IG com o briefing da campanha antes do lançamento: validação por API

Antes de lançar uma campanha, é possível comparar automaticamente uma lista de contas do IG com o briefing e gerar um CSV apenas com os registros que exigem atenção. Para cada linha, o script consulta o perfil, compara o nome de usuário, o status de privacidade e a verificação com os valores esperados e também salva os contadores disponíveis. Isso transforma uma conferência manual repetitiva em uma etapa de controle clara antes de encaminhar a campanha para execução.

Tarefa: encontrar divergências antes da publicação

Uma planilha de campanha normalmente contém o nome da conta e algumas expectativas: o perfil deve ser público, o nome de usuário deve corresponder ao que foi aprovado e o selo de verificação deve coincidir com o registro no briefing. Entre a preparação da lista e o lançamento, a conta pode mudar de nome, tornar-se privada ou revelar-se outro perfil com um nome semelhante. Quando as linhas são conferidas manualmente, é difícil repetir o processo e identificar rapidamente as exceções.

Para esse diagnóstico preliminar, basta obter o perfil pelo nome de usuário. A documentação publicada do jsonscraper especifica a rota GET /v1/user/by/username com o parâmetro username; também está disponível o parâmetro opcional cache_timeout. A resposta pode incluir nome de usuário, nome completo, indicadores de perfil privado e verificado, número de publicações, seguidores e contas seguidas, além da biografia. Os campos concretos devem ser lidos na resposta real: uma amostra do esquema confirma que estavam presentes na resposta observada, mas os valores podem variar ou estar ausentes.

Prepare a planilha e as regras de verificação

Crie um CSV profiles.csv com as colunas username, expected_private e expected_verified. Nessas duas colunas, informe os valores esperados true ou false e escreva o nome de usuário sem o símbolo @. Se a expectativa for desconhecida para algum perfil, deixe a célula vazia: o script não deve tratar a ausência de uma expectativa como erro.

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

A verificação resolve duas tarefas específicas: determina se o nome de usuário retornado corresponde ao solicitado e identifica diferenças em relação às expectativas registradas sobre privacidade e verificação. Os contadores e a biografia são salvos como contexto para avaliação manual, não como prova da qualidade da audiência ou da adequação do criador à campanha.

Conecte-se à IG Scraper API

Armazene a chave de acesso na variável de ambiente JSONSCRAPER_INSTAGRAM_LICENSE_KEY. Não inclua o segredo no CSV, no código-fonte nem nos registros de execução. A documentação do endpoint do IG descreve a rota e os nomes dos parâmetros; o endereço-base da API é https://ig.jsonscraper.com, e o nome do parâmetro da chave é license_key.

Antes de processar a lista completa, faça uma chamada de teste para uma linha de teste, confira a estrutura JSON e confirme que sua conta tem acesso. Como o endpoint aceita um nome de usuário, não são necessários identificadores de perfil conhecidos nem rotas adicionais para este cenário simples.

Exemplo: consultas, comparações e CSV de exceções

O script a seguir é compatível com Python 3.8 ou superior. Ele lê o CSV, faz uma solicitação GET por perfil, verifica o status HTTP da resposta e salva os campos relevantes originais junto com o resultado da comparação. Instale a dependência com o comando python -m pip install requests e, em seguida, exporte a chave antes de executar o script.

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)

O código verifica especificamente o invólucro da resposta observado: o status externo e o objeto de perfil ig. Se o provedor alterar o formato, a verificação da estrutura interromperá o processamento daquele registro e salvará um erro, em vez de gerar silenciosamente uma correspondência incorreta. O script não imprime a chave nem a inclui no arquivo de saída.

Como interpretar o resultado

No arquivo preflight_results.csv, as linhas com o status matched passaram nas comparações definidas. O valor review indica que um ou mais parâmetros diferem do briefing; a coluna checks mostra quais. Erros de solicitação ou resposta são indicados separadamente, para que a indisponibilidade dos dados não pareça uma correspondência confirmada.

O número de seguidores e de publicações ajuda a pessoa responsável a ver um retrato atual do perfil ao lado da solicitação. São valores instantâneos da resposta à consulta. Para avaliar mudanças ao longo do tempo, salve execuções separadas com data; uma única verificação não contém histórico. Alguns campos podem estar vazios. Nesse caso, o registro ainda pode ser usado para verificar a identidade e outros indicadores disponíveis, mas não para comparar um contador ausente.

Automatize antes do lançamento da campanha

Depois de verificar manualmente o CSV de teste, adicione o script a um agendamento ou a uma etapa de preparação da campanha. Para manter um controle reproduzível, armazene a lista original separadamente, registre a data da execução e salve o CSV de resultados em um repositório de trabalho com acesso restrito. Para reprocessamentos, é útil usar um identificador de linha estável do seu sistema, caso o nome de usuário possa mudar.

À medida que a lista crescer, adicione um limite de concorrência, novas tentativas apenas para erros de rede temporários e um registro separado de códigos de erro, sem segredos. Não faça tentativas ilimitadas para uma chave inválida ou um nome de usuário malformado. Só adicione o valor cache_timeout se ele estiver de acordo com a política de atualização necessária: a documentação informa que o cache do IG fica desativado por padrão e que um valor maior que zero o ativa pelo período definido.

A verificação de perfil reduz a conferência manual a uma lista específica de exceções: nome, privacidade, verificação e contadores disponíveis ficam em uma única planilha antes do início da campanha. Para consultar os parâmetros da API e as opções de integração atuais, use a página da IG Scraper API e a documentação das rotas.