Engenharia
Insira dados de links em um pipeline sem quebrá-lo
Puxar uma tabela uma vez é fácil. Puxá-la todo mês por um ano sem lacunas silenciosas é o verdadeiro trabalho.
Equipe de pesquisa da SEOCheck ·

Um job mensal em doze linhas
Python, apenas biblioteca padrão. Ele pagina pelos domínios de referência e para em um erro alto. Cada resposta coloca suas linhas em rows; adicione per (10 a 5000) para páginas maiores, e o loop para assim que tiver lido total linhas.
import json, urllib.request as u
KEY='sk_live_...'
def get(**p):
q='&'.join(f'{k}={v}' for k,v in p.items())
url=f'https://seocheck.dev/api.php?{q}&key={KEY}'
with u.urlopen(url) as r:
return json.load(r)
rows, page = [], 1
while True:
d = get(action='refdomains', q='example.com', page=page)
if not d['ok']: raise SystemExit(d)
rows += d['rows']
if not d['rows'] or len(rows) >= d['total']: break
page += 1
print(len(rows), 'of', d['total'], 'balance', d['_credits']['balance'])Por que jobs de api de backlink seo falham silenciosamente
Não com um crash. Com uma tabela que está faltando a última página. A causa usual é um loop que termina em um palpite em vez de em uma contagem.
Verifique três coisas em cada execução. ok voltou true? A contagem de linhas atingiu total? _credits mostrou o saldo que você espera? Se alguma resposta for não, falhe o job e avise alguém.
Sucesso silencioso é pior que uma falha barulhenta. Um job que termina com as linhas erradas parece saudável até alguém ler a planilha.
Limites de taxa e respostas lentas importam menos aqui do que em muitas APIs. Um job mensal pode simplesmente tentar novamente uma hora depois. O que importa é que as tentativas não cobrem duas vezes você por uma chamada que já teve sucesso. Registre o saldo de _credits antes e depois de cada execução e compare. Um salto maior do que o custo esperado do job significa que algo loopou. Investigue isso antes da próxima execução.
Equipes que já executam Airflow ou um cron simples em um pequeno servidor não precisam de nada novo. Um agendamento do GitHub Actions também funciona. A estrutura permanece a mesma: buscar, validar, armazenar, alertar. Veja a comparação de custos se você está avaliando isso contra uma exportação de suíte.
Armadilhas comuns de ingestão
| Armadilha | Sintoma | Correção |
|---|---|---|
| Filtragem client-side após a paginação | Execuções lentas, páginas desperdiçadas | Use sort e order server-side, depois corte |
| Paginação além do limite | Loop nunca termina | Paginação profunda para em 50.000 linhas; planeje-se para isso |
| Tratar HTTP 402 como um bug | Job tenta novamente para sempre | 402 significa que os créditos acabaram; recarregue, não tente novamente |
| Tratar 401 como transitório | Igual | Chave inválida; alerte e pare |
| Comparando meses cegamente | Quedas fantasmas | Atualizações de índice mensais; compare similar com similar |
| Misturando fornecedores de pontuação | Tendências sem sentido | Uma fonte por planilha |
Uma forma sensata para o todo
Mantenha uma lista de domínios em um só lugar
Uma planilha ou uma tabela. Uma coluna de domínios, nada mais no início.
Pontue a lista com bulk_dr
Até 2.000 domínios por chamada, um crédito. GET com domains= ou POST a lista como o corpo quando for longa.
Puxe detalhes apenas para os sobreviventes
Execute refdomains ou anchors na fatia superior. Dois créditos por chamada, até 1.000 linhas cada.
Armazene snapshots, não substituições
Data cada puxada. Tendências precisam de histórico.
Alerte sobre mudanças
Uma queda de DR de vários pontos em um domínio de fornecedor vale uma mensagem.
Google Sheets e CORS
CORS está aberto, então um snippet de navegador ou um Apps Script pode chamar a API diretamente. Um pequeno exemplo para uma função de célula. A função retorna a Domain Rating do domínio na célula.
function DR(domain){
var url='https://seocheck.dev/api.php?action=domain&q='+encodeURIComponent(domain);
var r=JSON.parse(UrlFetchApp.fetch(url).getContentText());
return r.metrics.dr;
}
Atualidade e honestidade
O índice é reconstruído cerca de uma vez por mês a partir do nosso próprio crawler. Espere atraso. Dados com mais de algumas semanas são normais. Não agende puxadas horárias; elas retornam a mesma coisa e custam créditos.
Escolha o dia após a atualização quando puder. Caso contrário, execute no mesmo dia todo mês e aceite o pequeno atraso.
Suítes completas de palavras-chave, crawls diários e rastreamento de posições vivem em outro lugar. Ahrefs e Semrush cobrem isso; leia a comparação de custos antes de duplicar qualquer coisa. A referência de endpoints tem todos os parâmetros.

Projetando o job para que você possa confiar nele
Um pipeline é tão bom quanto sua execução mais fraca. Construa cada execução para deixar evidências, para que um mês ruim possa ser explicado em vez de adivinhado. O trabalho extra é pequeno. Economiza muita discussão depois, e também economiza créditos.
Pense em quatro etapas: buscar, validar, armazenar e alertar. Mantenha cada uma simples. Cada etapa deve ser capaz de falhar sozinha, e cada falha deve dizer qual etapa quebrou. As mesmas quatro etapas se aplicam a qualquer job de api de backlink seo, independente da linguagem em que você o escreva.
Armazene a resposta bruta antes de transformá-la
Salve o JSON exatamente como ele voltou, com a data e os parâmetros da chamada no nome do arquivo ou em uma linha de cabeçalho. Quando um número parecer errado no próximo trimestre, você pode voltar ao que a API realmente disse em vez de para uma planilha que alguém editou.
Arquivos brutos custam pouco para manter. Uma planilha que foi substituída três vezes não pode dizer o que aconteceu em março.
Mantenha um log de execução com a contagem de linhas e saldo
Cada execução deve adicionar uma linha a um log: a hora de início, as chamadas feitas, as linhas retornadas, o valor de total e o saldo de _credits. O log é o primeiro lugar para olhar quando um número muda.
Se as linhas retornadas não corresponderem a total, a execução está incompleta. Marque-a como falha, mantenha o arquivo parcial e não o mescle na tendência.
Separe tentativas de novas execuções
Uma tentativa repete uma chamada que falhou sem resposta. Uma nova execução repete um job inteiro que terminou mas precisa ser refazido. Trate-os diferentemente, porque uma tentativa de uma chamada que na verdade teve sucesso pode custar créditos duas vezes.
Se você não consegue dizer se uma chamada teve sucesso, leia o log antes de enviá-la novamente. Esse único hábito evita a maioria dos encargos surpresa.
Alerte sobre as falhas que importam
Um alerta só é útil quando alguém age sobre ele. Envie um para uma chave falha, um saldo vazio, uma contagem de linhas que não corresponde a total e um custo muito acima da figura esperada. Deixe os sucessos rotineiros fora da mensagem, ou as pessoas deixarão de lê-la.
Agendamento sem desperdiçar créditos
O agendamento deve seguir os dados, não o relógio. Um job que roda a cada hora paga pela mesma snapshot vinte e quatro vezes por dia, é por isso que o ritmo mensal importa tanto para esse tipo de trabalho.
Escolha um agendamento uma vez e anote-o. Mudá-lo todo mês é como uma linha de tendência pega degraus artificiais.
Mensal vence horário para esses dados
O índice é reconstruído cerca de uma vez por mês. Puxadas mais frequentes que isso retornam a mesma coisa e custam créditos. Se você precisar de uma execução extra, faça-a após uma atualização conhecida, não no meio de uma.
Um job, muitos domínios
Coloque todos os domínios em uma única lista e execute a pontuação em uma única passagem. Uma chamada bulk_dr lida com até 2.000 domínios por um crédito, então uma lista de 1.500 prospects custa o mesmo que uma lista de dez. Divida o trabalho apenas quando um domínio precisar de dados mais profundos, como refdomains.
Mantenha a lista em um só lugar. Duas cópias de uma lista de domínios se separam, e então sua tendência compara conjuntos diferentes de sites.
Quem deve ser dono do job
Dê ao job um único dono, mesmo que ele rode em um servidor compartilhado. Alguém deve responder quando o alerta disparar, verificar o saldo e decidir se um mês falho precisa de uma nova execução. Sem um dono, um job que falha silenciosamente pode passar despercebido por um trimestre. Escreva o nome do dono no cabeçalho do log, para que a próxima pessoa saiba a quem perguntar.
Teste em uma lista pequena primeiro
Quando você mudar um job, execute-o em cinco domínios antes de apontá-lo para a lista completa. Um erro em um loop mostra-se em segundos em uma amostra pequena e em créditos em uma grande. O teste de cinco domínios custa quase nada. Cinco domínios são suficientes para mostrar um loop.
Mantenha essa lista de teste no repositório junto ao job, para que seja a mesma toda vez que você verificar.
Quando um pipeline é a resposta errada
Um pipeline ganha seu lugar quando você precisa dos mesmos números repetidas vezes. Escolha a ferramenta certa. Para uma única pergunta, uma puxada manual é frequentemente a melhor ferramenta. Seja honesto sobre qual dos dois você realmente precisa.
A outra razão para pular o pipeline é a forma do trabalho. Se a pergunta muda toda semana, um job fixo continuará medindo a coisa errada.
Uma exportação única não é um pipeline
Digamos que você precise dos domínios de referência de um rival para uma única proposta. Execute refdomains uma vez, salve o arquivo e siga em frente. Construir um job agendado para isso adicionaria manutenção sem adicionar insights.
Quando seus números encontram outros dados
Dados de links respondem a um tipo de pergunta. Se você precisa juntá-los com rankings de palavras-chave, conversões ou logs de chamadas, mantenha a junção no seu próprio sistema e mantenha a snapshot de links como uma entrada. Não espere que a API segure as outras fontes para você.
Decida o que você mantém, e por quanto tempo
Decida, antes da primeira execução, quais campos você armazena e por quanto tempo os mantém do seu lado. Reduza as linhas que você não precisa. Um arquivo menor é mais fácil de compartilhar com um cliente ou colega, e mais fácil de excluir quando o projeto termina.
A referência de endpoints lista todos os campos e o custo de cada chamada, o que torna essa decisão mais fácil de anotar.
Lista de pré-voo
- Chave armazenada como segredo, não no repositório.
- Loop termina na contagem de linhas, não na esperança.
- HTTP 401 e 402 tratados separadamente.
- Snapshots datados e mantidos.
- Um fornecedor de pontuação por tabela.
- Agendamento mensal, não horário.