Guia da API para agentes

URL base e formato da requisição

As solicitações usam https://seohabit.com/api/v1. Envie corpos JSON com Content-Type: application/json. Os projetos de sites e o progresso dos envios automáticos exigem autenticação. A frequência das solicitações é limitada.

Rastrear envios de terceiros

Crie um projeto com detalhes de diretório autorizado para habilitar submissão automática para fornecedores elegíveis. São feitas no máximo duas tentativas por dia UTC, interrompendo após cinco diretórios reconhecidos. O SEOHabit seleciona diretórios elegíveis em segundo plano; os usuários não navegam nem selecionam uma lista de diretórios. Se nenhum fornecedor elegível estiver disponível, o projeto aguarda. Um reconhecimento não é publicação nem um link de verificação.

Consultar estado da tarefa

Pole o URL de status até que o trabalho atinja completed ou failed. Autentique cada consulta com o token do trabalho no cabeçalho. Um token de trabalho concede acesso apenas ao próprio trabalho.

curl 'https://seohabit.com/api/v1/jobs/job_example' \
  -H 'X-Access-Token: YOUR_JOB_ACCESS_TOKEN'

As respostas incluem queued, running, completed ou failed; result é nulo até estar disponível.

Contas, chaves de projeto e ações pagas

O cadastro e login definem um cookie HttpOnly sh_session. Gravações de cookie no navegador são verificadas por origem. Para integrações, uma conta autenticada pode criar uma chave de API com escopo específico e enviá-la como Authorization: Bearer shk_…. As chaves não podem acessar outro projeto e os escopos das chaves limitam as operações disponíveis. Mantenha os cookies de sessão e as chaves de API secretas; nunca as inclua em URLs.

Tarefas de palavras-chave aceitam details.keyword, opcional details.language (padrão en) e um details.pageUrl explícito opcional. Sugestões exibem evidência de página correspondente e marcam linguagem desconhecida ou demanda de busca não confirmada.

Auditorias de site podem ser agendadas em um projeto gratuito dentro do limite gratuito. Submissões de backlinks monitorados, criação de tarefas e execução de tarefas exigem um site verificado e uma assinatura ativa. Uma ação paga exige que uma pessoa estabeleça a posse e obtenha explicitamente a assinatura pelo fluxo de faturamento da conta. Não inicie o checkout, assinatura ou autorize alterações por terceiro. A execução de tarefa não é prova de que uma alteração foi aplicada; uma tarefa pronta exige revisão e aceitação do usuário.

Chaves de projeto suportam project:read, project:write, checks:write e tasks:write. Uma chave aplica-se apenas ao seu próprio projeto. Consulte o Documento OpenAPI para rotas e formas de requisição.

Erros e uso seguro

Erros usam JSON com error e message. Respostas comuns incluem 400 para entrada inválida ou URLs não seguras, 401 para falta de autenticação de conta, 403 para origem não permitida ou escopo não autorizado, 404 para recursos indisponíveis, 409 para conflitos, 429 para limites de taxa e 402 quando uma ação paga exige uma assinatura ativa.

Verifique apenas páginas públicas que tenha autorização para inspecionar. O serviço bloqueia destinos privados e de rede local e segue a política do crawler do site fonte, quando disponível. Utilize chaves de idempotência para requisições POST reutilizáveis e trate respostas de limite de taxa com backoff.