Endereço de produção e primeiro pedido
Entre na aplicação emhttps://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.
- 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. - Copie já a chave completa: só aparece uma vez. O prefixo mostrado depois não autentica pedidos.
- Escolha um exemplo. Com cURL, introduza a chave quando solicitada. Para JavaScript ou Go, defina
SORANK_API_KEYno ambiente do processo servidor. O separador HTML inclui um servidor Node.js local: execute-o com a chave no ambiente e abrahttp://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.
- cURL
- HTML
- JavaScript
- Go
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 emhttps://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
ConsultegetQuotas 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.listProfilesdevolve apenas os sites elegíveis.- Um onboarding por concluir devolve
403 onboarding_required. - Um site sem subscrição válida devolve
402 subscription_required, comdetails.reason(paused,past_due,incompleteouinactive) quando conhecido.
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):listProductspercorre o catálogo de produtos com um cursor. Após409 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.starteend(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 recebe409 gsc_not_connectedou409 ga_not_connected, e403 google_access_lostse 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):getSettingsdevolve o site, o brief de negócio com a suarevision, os concorrentes, as predefinições dos artigos, os visuais e o canal do YouTube.
Alterar definições
Comsettings: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. ConsultegetCapabilities antes de escolher destino ou categoria CMS.
Acompanhar e repetir
Cada alteração requer umIdempotency-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_scopeou403 onboarding_required;402 subscription_requiredou402 insufficient_quota.404 not_found: o recurso não existe ou não é acessível com esta credencial.409: um conflito comoidempotency_conflict;429 rate_limited: aguardeRetry-After.503 auth_state_unavailable: o acesso é recusado até o estado de autorização recuperar; tente mais tarde.
code e request_id com o suporte, nunca o token.
Para ligar um assistente, consulte o guia MCP.
