Como encontrar vídeos do TikTok com divulgações publicitárias e encaminhá-los para revisão

Se uma equipe precisa verificar como criadores divulgam sua relação com uma marca em vídeos públicos do TikTok, um primeiro resultado útil não é um veredito automatizado, mas uma fila compacta de vídeos com legenda, link e palavras indicadoras encontradas. A seguir, apresentamos um fluxo de trabalho: enviar uma consulta de pesquisa pela TikTok Scraper API da jsonscraper, normalizar os dois formatos de resposta em uma estrutura única e salvar um CSV para revisão por um especialista.

Objetivo: encontrar vídeos que merecem ser revisados

É difícil repetir sempre da mesma forma uma pesquisa manual pelo nome de uma empresa: é preciso reunir os resultados um a um, e os motivos da seleção ficam no navegador. Uma coleta automatizada permite salvar a consulta, a data da execução e os materiais encontrados em uma planilha, para que a equipe possa revisar os vídeos com base em uma lista padronizada.

Neste cenário, «candidato à revisão» significa apenas um vídeo que aparece nos resultados da pesquisa e cuja descrição contém uma palavra ou frase definida previamente. Por exemplo, pode ser «publicidade», «parceria» ou «patrocinado». Esse filtro textual ajuda a direcionar a atenção de uma pessoa, mas não avalia o vídeo nem determina se os requisitos aplicáveis foram cumpridos.

Essa distinção é importante para uma equipe de marketing. As orientações da FTC para criadores explicam, com exemplos, que a divulgação de uma relação material com uma marca depende do contexto da mensagem; para vídeos, a FTC recomenda considerar se a divulgação é visual e audível. Uma pesquisa pelas legendas pode identificar alguns sinais textuais, mas a decisão exige assistir à publicação e avaliar seu contexto.

Resultado: um CSV com o motivo da seleção

O pipeline registrará uma linha por identificador de vídeo único e incluirá o texto da descrição, o link, o nome do autor, os contadores públicos disponíveis e os marcadores correspondentes. Também adicionaremos a consulta de pesquisa original e o horário da coleta. Isso torna a planilha adequada para ser encaminhada a uma fila de trabalho e ajuda a entender, posteriormente, por que determinado vídeo foi incluído.

O vocabulário de marcadores deve ser definido por um editor ou especialista em conformidade. Comece com o idioma e os termos realmente usados na sua campanha; em seguida, revise os resultados e amplie a lista se necessário. Os valores do código abaixo são intencionalmente simples: substitua-os de acordo com a marca, o mercado e o idioma do conteúdo.

Conexão com a TikTok Scraper API

A documentação da jsonscraper indica a rota GET /searchVideo, no endereço-base https://tiktok.evelode.com, para pesquisar vídeos. O parâmetro obrigatório é keyword; entre os parâmetros opcionais estão count, date_posted, sort_by e region. A chave é enviada como license_key, portanto, armazene-a em uma variável de ambiente, não no código nem no CSV. Os nomes exatos dos parâmetros e a rota constam no guia de endpoints do TikTok; informações sobre o produto e o acesso estão na página da TikTok Scraper API.

Há uma particularidade na resposta que afeta a abrangência do parser local: os dados podem estar em tiktok.aweme_list ou em tiktok.search_item_list[].aweme_info. Por isso, o script verifica os dois arrays. Se a pesquisa retornar uma lista vazia, ele criará um CSV vazio, em vez de inventar linhas para preencher a ausência de resultados.

Exemplo em Python: pesquisa, filtro e CSV

O exemplo usa apenas a biblioteca padrão do Python 3.8 ou superior. Antes de executá-lo, defina JSONSCRAPER_TIKTOK_LICENSE_KEY no ambiente. A solicitação usa keyword, e a chave é passada no parâmetro de consulta license_key, conforme indicado na especificação.

import csv
import json
import os
import sys
from datetime import datetime, timezone
from urllib.parse import urlencode
from urllib.request import Request, urlopen

API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
KEYWORD = "Acme"
MARKERS = ["реклама", "партнерство", "партнёрство", "спонсор", "ad", "sponsored"]

params = {
    "license_key": API_KEY,
    "keyword": KEYWORD,
    "count": 30,
    "sort_by": "date-posted",
    "date_posted": "this-month",
    "region": "US",
}
url = "https://tiktok.evelode.com/searchVideo?" + urlencode(params)
request = Request(url, headers={"Accept": "application/json"})

with urlopen(request, timeout=30) as response:
    payload = json.load(response)

if payload.get("status") != "ok":
    raise RuntimeError("API returned a non-ok outer status")

tiktok = payload.get("tiktok") or {}
items = list(tiktok.get("aweme_list") or [])
for entry in tiktok.get("search_item_list") or []:
    info = entry.get("aweme_info") or {}
    if info:
        items.append(info)

seen = set()
rows = []
collected_at = datetime.now(timezone.utc).isoformat()

for item in items:
    video_id = item.get("aweme_id")
    if not video_id or video_id in seen:
        continue
    seen.add(video_id)

    description = item.get("desc") or ""
    lowered = description.casefold()
    matched = [word for word in MARKERS if word.casefold() in lowered]
    if not matched:
        continue

    author = item.get("author") or {}
    stats = item.get("statistics") or {}
    rows.append({
        "collected_at_utc": collected_at,
        "search_keyword": KEYWORD,
        "video_id": video_id,
        "share_url": item.get("share_url") or "",
        "description": description,
        "matched_markers": "; ".join(matched),
        "author_name": author.get("nickname") or "",
        "author_id": author.get("unique_id") or "",
        "play_count": stats.get("play_count", ""),
        "digg_count": stats.get("digg_count", ""),
        "comment_count": stats.get("comment_count", ""),
        "share_count": stats.get("share_count", ""),
    })

fields = [
    "collected_at_utc", "search_keyword", "video_id", "share_url",
    "description", "matched_markers", "author_name", "author_id",
    "play_count", "digg_count", "comment_count", "share_count",
]
with open("tiktok_review_queue.csv", "w", newline="", encoding="utf-8-sig") as output:
    writer = csv.DictWriter(output, fieldnames=fields)
    writer.writeheader()
    writer.writerows(rows)

print(f"Saved {len(rows)} review candidates to tiktok_review_queue.csv")

Primeiro, o script verifica o status externo; em seguida, lê o objeto tiktok e combina os arrays disponíveis. A deduplicação por aweme_id evita linhas repetidas caso o mesmo vídeo apareça nos dois caminhos de resposta. As métricas são registradas como recebidas; valores ausentes permanecem vazios, em vez de serem convertidos em zero.

O exemplo usa parâmetros documentados para /searchVideo: date_posted aceita o valor this-month, sort_by aceita date-posted e region recebe um código de país. O valor de count define o tamanho dos resultados solicitados, não garante uma lista completa de publicações. Ao implementar a paginação, armazene o cursor retornado como um valor opaco e passe-o no parâmetro cursor.

Revisão humana e automação da execução

Encaminhe o CSV à pessoa responsável pela revisão, junto com instruções breves: abrir o link, assistir ao vídeo, considerar o contexto da legenda, registrar uma conclusão e comentar quando o marcador tiver outro sentido. Por exemplo, a filtragem automática não distingue uma divulgação publicitária de uma discussão sobre como a publicidade funciona. A revisão humana preenche essa lacuna semântica.

Para repetir a coleta, execute o script em intervalos programados usando cron, um agendador de CI ou um orquestrador de tarefas. Salve o CSV com a data da execução ou carregue as linhas em uma tabela com uma chave exclusiva composta pelo identificador do vídeo e a data de observação. Se precisar de um registro de auditoria, armazene também a resposta JSON original com controles de acesso: isso permite verificar novamente a transformação e explicar a origem de cada linha.

Em uma versão de produção, vale a pena adicionar tratamento de erros de rede e HTTP, limitar as tentativas e emitir notificações em caso de falha. Não imprima o URL completo da solicitação: ele contém a chave de acesso. Para equipes com vários usuários, é recomendável armazenar o segredo em um gerenciador de segredos do ambiente de execução e restringir o acesso aos arquivos finais de acordo com as políticas internas.

O que essa lista oferece

Após a execução, a equipe terá uma seleção reproduzível de vídeos encontrados por uma frase-chave e um motivo explícito para a inclusão de cada candidato na fila. A planilha permite excluir manualmente correspondências irrelevantes, designar revisores e agrupar resultados por marcador ou autor. Se a coleta for executada regularmente, também será possível manter um histórico dos vídeos presentes nos resultados retornados em determinada data.

Essa abordagem é adequada para a descoberta inicial e o encaminhamento de materiais, não para concluir automaticamente se as regras foram cumpridas. Ela está limitada aos resultados da pesquisa, à palavra-chave escolhida, às configurações da solicitação e aos marcadores textuais. Para verificar uma colaboração específica, compare o vídeo com o briefing e com as informações disponíveis para sua equipe; em seguida, avalie a própria mensagem de acordo com as regras aplicáveis.

Para começar, consulte as informações atualizadas sobre acesso e parâmetros na página do produto TikTok Scraper API e confira o formato da resposta e as opções de integração na documentação oficial da API.