API pública: chaves, escopos e cenários
A API pública permite que você gerencie a divulgação a partir do seu sistema: criar projetos, adicionar páginas, lançar cascatas, obter relatórios, além de trabalhar com verificações de posições, auditorias e varreduras de segurança.
Documentação
O guia completo, com parâmetros e exemplos de requisições, está disponível em uma página separada e sempre corresponde à versão atual. Aqui está apenas um panorama geral.
Chaves e Permissões
- A chave é emitida na área do cliente, na seção "API para Desenvolvedores", e é enviada no cabeçalho de autorização.
- A chave tem scopes, ou seja, conjuntos de permissões. São quatro: promotion, rank, audit, shield. Emita apenas o que for realmente necessário.
- A chave pode ser revogada a qualquer momento; as requisições antigas feitas com ela deixam de funcionar imediatamente.
- Há um limite de frequência de requisições; as estatísticas de chamadas e gastos por chave ficam visíveis na área do cliente.
O que Está Disponível via API
| Grupo | Recursos | Scope |
|---|---|---|
| Conta | Perfil, saldo, desconto pessoal, informações da chave | não é necessário |
| Projetos e Links | Criação de projetos, adição e exclusão de páginas | promotion |
| Divulgação | Tarifas, pré-cálculo, lançamento de cascata, status e lista de publicações | promotion |
| Relatórios e Marca | Relatório em JSON ou PDF, configurações de white-label (somente Pro) | promotion |
| Rank Tracker | Projetos, palavras-chave, configuração de verificações de posições | rank |
| SEO Audit | Estimativa do tamanho do site, rastreamento expresso e completo, resultados com Health Score | audit |
| Shield | Verificação de domínio, lançamento de varreduras, veredito | shield |
A personalização de marca nos relatórios não é um scope separado: ela está incluída em promotion e exige uma assinatura Pro ativa.
Cenário Típico
- Crie um projeto e adicione páginas a ele.
- Solicite o cálculo de custo para a configuração de cascata desejada.
- Lance a divulgação e salve o ID do lançamento.
- Consulte o status periodicamente e, ao concluir, solicite o relatório com as publicações.
O pré-cálculo retorna o valor com desconto e o saldo atual, para que o preço possa ser exibido antes da cobrança; como ele é composto está no artigo tarifas e preço. O relatório retorna apenas as publicações confirmadas, como na área do cliente: os valores de status são explicados no artigo relatório e status.
Limites e Códigos de Resposta
| Situação | Resposta | O que Fazer |
|---|---|---|
| Chave não informada, não encontrada ou revogada | 401 | Verifique o cabeçalho de autorização e a própria chave |
| A chave não tem o scope necessário | 403 | Emita uma chave com as permissões necessárias |
| Saldo insuficiente para o lançamento | 402 | A resposta incluirá o valor necessário, o saldo, a diferença faltante e um link para recarga |
| Erro nos parâmetros ou domínio do link de outro proprietário | 422 | O campo com erro é indicado na resposta |
| Muitas requisições | 429 | Tente novamente após o número de segundos informado na resposta; o limite é contado por chave |
| Serviço temporariamente desativado | 503 | Tente novamente mais tarde: o lançamento não ocorreu e o dinheiro não foi debitado |
As listas são retornadas com paginação, com no máximo 100 itens por página. A lista completa de códigos está disponível no guia.
Erros Comuns de Integração
- Reinício do mesmo link. Enquanto uma cascata ativa está em andamento, uma nova não é criada: a resposta indicará "already active". Isso não é uma falha, não há necessidade de repetir a requisição em loop.
- Auditoria completa sem express, scan do Shield sem verificação de domínio. Ambas as ações exigem uma etapa preparatória, caso contrário será retornado um erro.
- Consulta de status com frequência excessiva. A cascata dura horas: consultar mais de uma vez a cada poucos minutos não faz sentido, e é fácil atingir o limite de frequência.
- Saldo zerado no momento do lançamento. O pré-cálculo pode ter ocorrido ontem, e o dinheiro pode ter sido usado em outros lançamentos: mantenha uma reserva, veja saldo e recarga.
White-label via API
Assinantes do Pro podem definir logotipo, nome da empresa e cor, e assim os relatórios obtidos via API serão exibidos com a sua marca. Mais detalhes no artigo sobre White-label.
O servidor armazena apenas o hash da chave, e exibir a chave emitida novamente é impossível: salve-a imediatamente. Chave perdida ou exposta em um repositório: revogue a antiga e emita uma nova, isso não afeta cascatas já iniciadas.
