Saltar para o conteúdo principal

Endereço de produção e primeiro pedido

Entre na aplicação em https://app.sorank.com. Faça a gestão das chaves em https://app.sorank.com/settings/api e envie pedidos para https://app.sorank.com/api/public/v1. Não precisa de criar um servidor API.
  1. Abra Definições → Acesso à API e crie uma chave com nome, pelo menos um site, Ver sites (profiles:read) e validade. Adicione Ver cotas (quotas:read) para o segundo pedido.
  2. Copie já a chave completa: só aparece uma vez. O prefixo mostrado depois não autentica pedidos.
  3. Escolha um exemplo. Com cURL, introduza a chave quando solicitada. Para JavaScript ou Go, defina SORANK_API_KEY no ambiente do processo servidor. O separador HTML inclui um servidor Node.js local: execute-o com a chave no ambiente e abra http://127.0.0.1:3100. Nunca coloque a chave em HTML ou JavaScript do navegador. Adicione a autenticação da sua aplicação antes de usar este modelo fora da demonstração local.
A resposta lista os sites autorizados em data. Use um valor data[].id como profile_id nos pedidos seguintes. Se a lista estiver vazia, verifique os sites escolhidos e o seu acesso. Os exemplos cURL, JavaScript e Go também consultam a quota do primeiro perfil com quotas:read. A Referência da API pública na navegação para programadores descreve caminhos, scopes e respostas.

Autenticar-se

Crie uma chave pessoal em Definições → Acesso à API para os seus scripts ou autorize um cliente OAuth com PKCE S256. Limite perfis e scopes ao necessário. Envie o token como Bearer. Cookies do navegador e tokens Supabase não autorizam esta API. Para uma aplicação que atua em nome do utilizador, comece em https://app.sorank.com/.well-known/oauth-protected-resource/api/public/v1 e https://app.sorank.com/.well-known/oauth-authorization-server. Descubra os endpoints OAuth anunciados, registe um cliente público se necessário e use authorization code com PKCE S256, os scopes necessários e o recurso exato https://app.sorank.com/api/public/v1. Um token OAuth MCP não serve para REST.

Permissões e quota

Consulte getQuotas antes de gerar. O exemplo requer profiles:read, quotas:read, calendar:read, calendar:write, articles:read, articles:generate e articles:publish. Criar um calendário também requer direitos de geração e publicação. A aplicação, REST e MCP partilham a quota; mais chaves não a aumentam. Os scopes de leitura Ver produtos (products:read), Ver análises (analytics:read), Ver visibilidade de IA (geo:read) e Ver configurações (settings:read) nunca consomem quota. Editar configurações (settings:write) altera as mesmas definições que a aplicação; conceda-o apenas se uma integração as tiver de alterar. O contrato 1.2 acrescenta permissões que as chaves e ligações existentes não têm: Pesquisar e gerar palavras-chave (keywords:generate), Ver melhorias (audit:read), Executar auditorias e corrigir artigos (audit:write), Atualizar produtos (products:write), Editar prompts de visibilidade de IA (geo:write), Ver backlinks (backlinks:read), Gerenciar backlinks e missões (backlinks:write) e Ver faturas (billing:read). Crie uma nova chave ou volte a ligar a aplicação para as conceder. A pesquisa de palavras-chave e as correções de artigos gastam os créditos de IA do site, não a quota de artigos: getQuotas devolve o saldo e o preço atual de cada ação em ai_credits.

Verificar a elegibilidade

A API fica disponível depois de concluir o onboarding na Sorank e se o site tiver uma subscrição válida. Um colaborador de agência usa a subscrição do proprietário do site. A Sorank verifica-o ao criar uma chave ou aprovar uma ligação OAuth, e novamente em cada pedido.
  • listProfiles devolve apenas os sites elegíveis.
  • Um onboarding por concluir devolve 403 onboarding_required.
  • Um site sem subscrição válida devolve 402 subscription_required, com details.reason (paused, past_due, incomplete ou inactive) quando conhecido.
Conclua o onboarding ou atualize a subscrição em Definições → Faturação. A sua chave existente volta a funcionar no pedido seguinte.

Ler produtos, análises, visibilidade de IA e definições

Estas leituras devolvem o que a aplicação Sorank lhe mostra. Nunca iniciam uma análise, uma sincronização ou uma geração.
  • Produtos (products:read): listProducts percorre o catálogo de produtos com um cursor. Após 409 product_catalog_cursor_stale, recomece na primeira página.
  • Análises (analytics:read): desempenho, pesquisas, páginas, países e dispositivos do Search Console, e tráfego do Google Analytics vindo de assistentes de IA. start e end (YYYY-MM-DD) são obrigatórios. Cada chamada lê o Google em tempo real e tem um limite de frequência mais baixo. Ligue primeiro o Google na Sorank; caso contrário recebe 409 gsc_not_connected ou 409 ga_not_connected, e 403 google_access_lost se o acesso tiver sido perdido.
  • Visibilidade de IA (geo:read): estatísticas GEO, evolução das menções, cronologia das citações, fontes que citam o site e concorrentes citados numa análise.
  • Definições (settings:read): getSettings devolve o site, o brief de negócio com a sua revision, os concorrentes, as predefinições dos artigos, os visuais e o canal do YouTube.

Alterar definições

Com settings:write, pode alterar o nome da empresa, a cor da marca e o mercado, substituir o brief de negócio e a lista de concorrentes, alterar as predefinições dos artigos do calendário, o modo de imagem e as capas, e ligar, pausar ou desligar o canal do YouTube. O URL do site não pode ser alterado através da API (400 field_not_writable). Cada alteração requer um Idempotency-Key. A resposta contém as definições resultantes, um recibo e uma lista effects com os processos iniciados em segundo plano, como na aplicação: geo_questions_regeneration_queued, backlink_refresh_queued, calendar_slots_shifted, image_gallery_analysis_queued, youtube_sync_queued ou youtube_purge_queued. Para substituir o brief de negócio, envie a expected_revision lida em getSettings. Se o brief tiver mudado entretanto, recebe 409 business_brief_revision_conflict: volte a ler as definições antes de repetir.

Pesquisar palavras-chave, corrigir artigos e gerir o resto

Estas operações fazem o mesmo que os ecrãs correspondentes do Sorank, com os mesmos limites e os mesmos preços em créditos de IA.
  • Palavras-chave (keywords:generate): researchKeywords e getKeywordMetrics devolvem palavras-chave com volume, dificuldade, CPC e intenção, como o chat SEO. generateKeywords inicia uma pesquisa completa de palavras-chave (202); acompanhe-a com getKeywordRun (keywords:read).
  • Melhorias (audit:read, audit:write): getAudit e listAuditPages devolvem a última auditoria e as páginas a corrigir. estimateAuditFixes calcula o preço de uma página ou do site inteiro sem debitar nada. fixAuditPage prepara correções ou uma reescrita, applyAuditFix escreve uma correção no seu CMS e restoreAuditFix repõe a versão anterior (ambas requerem também articles:publish). fixAuditBulk corrige o site inteiro (requer também articles:generate e articles:publish). startAudit inicia uma nova auditoria.
  • Produtos (products:write): refreshProductCatalog volta a analisar a sua loja, com o mesmo tempo de espera que na aplicação (429 rate_limited com Retry-After).
  • Indexação no Google (articles:read): getArticleIndexStatus devolve o estado de indexação que o Sorank já conhece de um artigo publicado.
  • Prompts de visibilidade de IA (geo:read, geo:write): listGeoPrompts, createGeoPrompts, updateGeoPrompt e deleteGeoPrompts, dentro do limite de prompts do seu plano (prompt_limit_exceeded).
  • Backlinks (backlinks:read, backlinks:write): getBacklinks e listBacklinkQuests devolvem as definições da rede, os seus créditos e as missões. updateBacklinkSettings ativa ou desativa a rede, e claimBacklinkQuest envia a prova de uma missão para revisão.
  • Faturas (billing:read): listInvoices devolve as faturas da subscrição deste site com uma ligação para o PDF.

Experimentar um fluxo REST completo

Este exemplo avançado cria conteúdo e pode consumir quota. Substitua os IDs, datas futuras, chaves de idempotência e credencial de exemplo antes de o executar. As datas do calendário usam o fuso IANA indicado. Consulte getCapabilities antes de escolher destino ou categoria CMS.
A referência da API pública descreve operações, campos, respostas e erros.

Acompanhar e repetir

Cada alteração requer um Idempotency-Key único. Reutilize a mesma chave ao repetir o mesmo comando. Leia data.receipt.operation_id e consulte getOperation até succeeded, failed ou verification_pending. Um recibo aceite não confirma a publicação. Um lote de geração de artigos devolve 202 com um recibo já succeeded; acompanhe cada artigo indicado em selection.accepted_ids com getArticle. Os direitos são verificados em cada consulta; a revogação tem efeito imediato. Num site Framer, getPublication também devolve site_deploy. O Framer só mostra uma alteração depois de uma publicação do site, que o Sorank inicia cerca de um minuto após cada alteração: pending significa que public_url ainda não mostra a última alteração, e live que ela já está online. Enquanto o estado for pending, last_error_code indica o erro da última implementação falhada, por exemplo cms_token_expired quando a chave API do Framer tem de ser substituída. Quando uma publicação falha, getPublication devolve status failed com last_error.code publication_failed. Quando o Sorank registou a causa, last_error.reason indica-a, por exemplo site_unreachable: o Sorank não conseguiu ligar-se ao site, por isso verifique se está online e se o alojamento ou a firewall não bloqueiam o Sorank. Podem ser adicionadas novas causas: trate uma causa desconhecida como uma falha genérica. Numa loja PrestaShop ligada com uma chave de Webservice, sem o módulo Sorank, updatePublishedArticle não consegue alterar o endereço de uma página publicada. Se alterou o slug do artigo, a operação termina em failed com publication_change_failed. Reponha o slug publicado ou instale o módulo Sorank na loja.

Tratar erros

Todos os erros têm a mesma forma em REST e MCP: {"error": {"code", "message", "request_id", "retryable", "details"}}. Baseie a sua lógica em code, não na mensagem. Repita apenas quando retryable for true, após Retry-After quando presente.
  • 401 invalid_credential: credencial inválida, expirada ou revogada.
  • 403 missing_scope ou 403 onboarding_required; 402 subscription_required ou 402 insufficient_quota.
  • 402 insufficient_credits: o saldo de créditos de IA não cobre a ação; details.required e details.balance indicam os valores.
  • 404 not_found: o recurso não existe ou não é acessível com esta credencial.
  • 409: um conflito como idempotency_conflict; 429 rate_limited: aguarde Retry-After.
  • 503 auth_state_unavailable: o acesso é recusado até o estado de autorização recuperar; tente mais tarde.
  • 503 service_unavailable: o Sorank está temporariamente indisponível; aguarde Retry-After e repita uma escrita com a mesma Idempotency-Key.
A referência da API pública indica os códigos de cada operação. Partilhe code e request_id com o suporte, nunca o token. Para ligar um assistente, consulte o guia MCP.