Contador de backlinks para um painel SaaS, passo a passo
Um contador funcional precisa de uma rota de servidor e de um pequeno componente. Este guia constrói ambos, incluindo os estados de falha que a maioria das primeiras versões esquece.
Equipe editorial AlfaLinks ·
Escopo deste guia
Partimos do pressuposto de um backend Node ou Python e qualquer framework front-end. Cada solicitação abaixo atinge a API documentada, e a URL base é a do seu próprio domínio: alfalinks.net/api.php.
Cinco etapas, na ordem em que as implementaríamos
01
1. Crie a chave e armazene-a como segredo
Faça login com o Google em /auth/google.php, copie a chave sk_ da página da conta e coloque-a no ambiente do seu servidor. O front-end nunca a vê.
02
2. Adicione uma rota de proxy
Exponha algo como /internal/links?domain=... que valide o domínio, chame nossa API e retorne apenas os campos que sua interface usa. A validação é importante porque os usuários digitam qualquer coisa.
03
3. Comece com a ação gratuita
A ação overview não tem custo, então a primeira versão do contador não tem risco de cobrança alguma. Passe para ações pagas quando uma tela precisar delas.
04
4. Renderize três estados
Carregando, dados e indisponível. O estado indisponível cobre HTTP 401, HTTP 402 e falha de rede, e nunca deve mostrar um zero.
05
5. Adicione a etiqueta de atualização
Nosso índice é atualizado aproximadamente uma vez por mês. Uma linha cinza com o texto 'dados de links atualizados mensalmente' evita o ticket de suporte que começa com 'Adicionei um link ontem'.
A rota de proxy, em Node
Curta o suficiente para ser lida em uma tela. O cache é um Map simples aqui; substitua por Redis quando executar mais de um processo.
js
const cache = new Map();
const MONTH = 30 * 24 * 3600 * 1000;
app.get('/internal/links', async (req, res) => {
const domain = String(req.query.domain || '').toLowerCase().trim();
if (!/^[a-z0-9.-]+\.[a-z]{2,}$/.test(domain)) return res.status(400).json({ok:false});
const hit = cache.get(domain);
if (hit && Date.now() - hit.t < MONTH) return res.json(hit.v);
const r = await fetch(`https://alfalinks.net/api.php?action=overview&q=${domain}`);
if (!r.ok) return res.status(502).json({ok:false});
const v = await r.json();
cache.set(domain, {t: Date.now(), v});
res.json(v);
});
Adicionando um crachá DR quando o contador estiver funcionando
O contador é a parte fácil. O crachá precisa de uma chamada extra.
Para uma tabela de domínios de clientes, envie uma única solicitação bulk_dr com até 2.000 domínios em vez de uma chamada por linha. Custa 1 crédito independentemente do número de linhas, e a resposta mapeia cada domínio para seu valor de 0-100, que você armazena ao lado da visão geral em cache.
Corresponda os domínios pelo hostname normalizado. Remova o esquema, o caminho e um 'www' inicial, ou metade das suas linhas perderá a consulta e mostrará espaços em branco.
Mostre um valor primeiro, depois peça a configuração
Novos usuários raramente leem uma página de configuração. Eles querem ver se o recurso vale o esforço, e um contador de backlinks que mostra um valor real responde a isso mais rápido do que qualquer formulário. Coloque o valor em primeiro lugar. A configuração vem em segundo.
Como a ação gratuita de visão geral não precisa de chave, sua primeira tela pode mostrar um valor antes que o usuário tenha configurado qualquer coisa.
O que o primeiro render precisa?
Apenas um domínio e uma chamada gratuita. Imagine um novo usuário que digita seu próprio site no onboarding e vê o contador aparecer na mesma visualização de página. Esse único valor faz mais para iniciar a configuração do que uma lista de etapas, então mantenha o resto da configuração atrás dele.
O usuário vê o que obterá antes que alguém peça um cartão, uma chave ou um segundo formulário. Nada no primeiro render deve parecer uma barreira.
Onde deve ficar o prompt de configuração?
Logo após o valor, não antes. Uma linha curta como 'Conecte um domínio para rastrear isso todos os meses' cabe abaixo do contador. Se o mesmo prompt ficar acima do valor, os usuários o leem como uma barreira e saem.
Acompanhe quais usuários concluem cada etapa de configuração. Um pequeno funil mostra onde as pessoas param, e uma mudança na redação muitas vezes move esse número mais do que um novo recurso.
Testes antes do lançamento
Teste primeiro os caminhos não felizes. Os caminhos felizes se testam sozinhos.
Revogue a chave no ambiente de staging e confirme que o cartão mostra 'indisponível' em vez de zero. Depois, esgote um saldo de teste para acionar um 402 e cole uma entrada malformada, como um domínio com esquema e caminho final, para provar que o validador o rejeita antes que qualquer crédito seja gasto.
Um teste rápido de fumaça pertence ao CI. Uma chamada gratuita overview em nytimes.com, executada diariamente, mostra que a rota e a chave ainda funcionam.
Quem pode consultar qual domínio e a que custo
Um contador que aceita qualquer string é uma porta aberta para o seu saldo. Decida quem pode pedir o quê antes que a rota vá ao ar, e escreva a resposta no código, não em uma página de wiki que ninguém abre.
Três perguntas surgem sempre: quais domínios, qual limite e onde a chave fica.
Quais domínios um usuário deve poder digitar?
Apenas aqueles para os quais o workspace tem uma reivindicação, mais quaisquer consultas públicas que você escolheu oferecer. Digamos que um workspace possua dois sites. A rota pode aceitar esses dois e rejeitar qualquer outro com uma mensagem clara, o que evita que um inquilino gaste créditos em domínios que não são seus.
A verificação de hostname na rota é o mínimo. Ela prova que a entrada parece um domínio, não que o usuário o possui, então mantenha a lista de reivindicações em seu próprio banco de dados como uma tabela separada.
Como você impede que um usuário esgote o saldo?
Coloque uma cota por workspace em seu próprio armazenamento e conte as chamadas lá. O saldo do nosso lado é um único pool pré-pago, então não pode dizer a você qual cliente gastou o quê. As notas da página de consulta cobrem o lado público do mesmo problema. Quando um workspace atinge seu limite, retorne uma mensagem simples e deixe o cache continuar respondendo com o que já possui.
Escolha o limite com base na aritmética das notas por assento, não de um palpite, e revise-o quando um plano mudar. Teste a rota com um segundo workspace antes de confiar na cota.
O navegador deve conter a chave?
Não. A chave fica no seu servidor, e o navegador chama sua rota. Essa divisão é também o que torna possível uma cota, já que cada chamada cobrada passa pelo código que você controla. Se uma chave aparecer em um bundle enviado, gire-a no mesmo dia e verifique o log de saldo por chamadas que você não fez. Algumas equipes armazenam a chave em um arquivo de configuração que o front-end lê em tempo de build, e esse arquivo acaba no bundle. Mantenha a chave fora de qualquer coisa que o passo de build possa ver, e verifique os arquivos enviados uma vez antes de cada lançamento.
As ações gratuitas podem ser chamadas de uma página pública sem uma chave, e esse é o único caso em que o navegador pode falar diretamente com a API.
O que o contador deve dizer, e o que não deve
Diga menos do que sabe. Um contador rotulado 'backlinks' convida à pergunta 'por que o Ahrefs mostra um número diferente?', e a resposta honesta é que dois crawlers veem duas fatias da web.
Rotule o valor com sua fonte e mês em vez disso. Algo como 'Domínios apontando, índice AlfaLinks, outubro de 2026' é mais longo, mas termina o argumento antes que ele comece e lê bem em um cartão pequeno.
Arredonde para exibição. Um usuário que vê 12.481 na segunda-feira e 12.481 na sexta-feira confia mais na ferramenta do que um que vê oscilações, e nossa atualização mensal lhe dá essa estabilidade gratuitamente.
Se você quiser o valor de 0-100 ao lado, leia as notas sobre pontuação de backlinks primeiro. É nossa própria métrica, então a nomenclatura importa.
Estados de falha e o que a interface faz
Os códigos HTTP são os retornados pela API; a coluna da interface é nossa sugestão.
Sinal
Significado
O que o usuário vê
O que você faz
HTTP 401
Chave ausente ou inválida
'Dados de links indisponíveis'
Auto-deploy: bug
HTTP 402
Créditos esgotados
'Dados de links indisponíveis'
Recarregue com USDT (TRC-20)
ok: false
Solicitação rejeitada
Link de retry inline
Registre o domínio e a ação
Tempo esgotado
Problema de rede
Valor em cache se você tiver um
Tente novamente uma vez, depois reduza a frequência
Mantendo o contador honesto no suporte e nos logs
Um contador falha silenciosamente muito mais frequentemente do que falha visivelmente. Registre o suficiente para responder à pergunta que o cliente fará em seguida, e mantenha os dados pessoais fora do log completamente. Linhas curtas vencem. Uma linha que responde a uma pergunta de suporte economiza mais tempo do que qualquer alerta que você possa escrever.
A maioria dos threads de suporte sobre um contador é uma de três perguntas, então planeje o log em torno delas. Mantenha essas três perguntas em seu runbook, ao lado das etapas para girar uma chave.
O que cada linha de log deve registrar?
A ação, o domínio, o código de status, a idade do cache e o saldo de créditos que voltou. Esses cinco campos respondem à maioria das perguntas de suporte. Digamos que um usuário pergunte por que seu contador mostra um valor antigo. A idade do cache e o mês do índice dizem a você se o problema é o cache ou o rótulo.
Deixe a chave da API fora de todas as linhas, incluindo rastros de erro. Mascare-a no logger, porque uma linha vazada pode esgotar toda a conta.
Como você sabe que o contador está saudável a cada semana?
Observe três números: a proporção de estados indisponíveis, a tendência do saldo de créditos e a taxa de acerto do cache. Um salto repentino nos estados indisponíveis geralmente aponta para um problema de chave ou saldo. Uma queda lenta no saldo geralmente aponta para uma chave de cache muito específica.
Cada leitura tem um ajuste diferente, é por isso que um único tile de dashboard para todos raramente ajuda alguém. Coloque as três leituras em uma linha na sua nota semanal, com o último valor e a mudança desde a semana anterior. Números lidos isoladamente convidam a suposições, enquanto uma tendência curta mantém a conversa nos mesmos fatos.
