Skip to main content

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.

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.

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.

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.
  • 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.
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.