Documentação da API

action=services

Lista todos os sites em que você pode fazer pedidos, com a taxa atual e os limites. Use o id `service` nas suas chamadas add.

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=services"

[
  {
    "service": 9,
    "name": "arena-top100.com 1000 upvotes",
    "type": "Default",
    "category": "Votes",
    "rate": 15,
    "min": 1,
    "max": 50000,
    "refill": false,
    "cancel": true
  }
]

`rate` é em tokens por 1.000 ações. `min` é 1 e `max` é 50000 para todos os serviços.

action=add

Cria uma campanha e debita o custo do seu saldo imediatamente.

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=add" \
  -d "service=9" \
  -d "link=https://arena-top100.com/index.php?a=in&u=yourserver" \
  -d "quantity=1000" \
  -d "interval=60"

{
  "order_id": 184223
}

action=status

Retorna o progresso de um ou mais pedidos. Passe um único id para um objeto simples, ou uma lista separada por vírgulas.

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=status" \
  -d "orders=184223"

{
  "charge": 13.5,
  "start_count": 0,
  "status": "Completed",
  "remains": 1000,
  "currency": "USD"
}

Com vários ids, a resposta é indexada pelo id do pedido, e pedidos desconhecidos ou de outra conta retornam uma entrada de erro em vez de derrubar a requisição inteira.

{
  "184223": { "charge": 13.5, "start_count": 0, "status": "Completed", "remains": 1000, "currency": "USD" },
  "184224": { "error": "Incorrect order ID" }
}

`status` e `cancel` aceitam no máximo 100 ids de pedido por chamada. Agrupe em vez de iterar: uma chamada com 100 ids é bem mais barata para os dois lados do que 100 chamadas.

action=balance

Retorna seu saldo restante de tokens.

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=balance"

{
  "balance": 528.41,
  "currency": "USD"
}

action=cancel

Interrompe um pedido e devolve o restante não gasto ao seu saldo. Pedidos concluídos não podem ser cancelados.

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=cancel" \
  -d "orders=184223,184224"

[
  { "order": "184223", "cancel": 1, "refund": 4.5 },
  { "order": "184224", "cancel": { "error": "Incorrect order ID" } }
]

Catálogo e descoberta#

Público, sem credencial. getAllWebsites é o endpoint por onde começar: traz o id, o preço, o teto por hora e a taxa de aceitação de que você precisa para precificar e dimensionar um pedido.

• GET/orders/getAllWebsitesPúblicaO catálogo completo: cada site com tarifas, limites e metadados
• GET/orders/getAllBasicWebsitesDetailsPública20 nomes de site aleatórios, para widgets e autocompletes
• POST/orders/getWebsiteDetailsByNamePúblicaUm site pelo nome exato
• POST/products/getSuggestionsPúblicaSites relacionados a um conjunto de ids
• GET/products/demand?days=30PúblicaO quanto cada site foi pedido recentemente
• GET/products/tokensPúblicaPacotes de tokens que você pode comprar
• POST/products/suggestChave de APIPeça para adicionarmos um site novo
• GET/api/news/timelinePúblicaNovidades do produto

curl "https://backend.toplistbot.com/orders/getAllWebsites"

Peça menos

O catálogo inteiro tem cerca de 665 KB em 396 sites, e dois campos com os quais você nunca vai fazer um pedido respondem por metade disso: um bloco JSON de popularidade e a descrição de marketing. Projete só os campos que usa para pedir e descarte os sites inativos e ele cai para uns 40 KB.

# The whole catalog is ~665 KB across 396 sites.
# Projected to what you actually order with: ~40 KB.
curl -s "https://backend.toplistbot.com/orders/getAllWebsites" \
  | jq '[.[]
      | select(.active == 1)
      | {id, name, price_per_1000, max_per_hour, accept_rate, subscribeable}]'

Conta e sessões#

O cadastro precisa de navegador: é protegido por um desafio da Cloudflare. Cadastre-se uma vez em app.toplistbot.com e automatize todo o resto.

• POST/api/auth/registerPúblicaCriar uma conta: só por navegador, protegido por captcha
• POST/api/auth/loginPúblicaTrocar credenciais por um JWT
• POST/api/auth/refreshJWTEmitir um JWT novo a partir de um que está expirando
• POST/api/auth/logoutJWTInvalidar o JWT atual
• GET/api/auth/user-profileJWTA conta logada, com saldo e chave de API
• GET/api/userJWTO mesmo objeto de usuário, num caminho mais curto
• GET/api/api_tokenChave de APIResolver uma chave de API para o dono: use para validar uma chave
• POST/api/auth/reset-api-keyJWTGirar sua chave de API; a antiga morre na hora
• POST/api/auth/fingerprintJWTRegistrar uma impressão de navegador na conta
• POST/api/auth/ipJWTRegistrar o IP atual da conta
• POST/api/auth/forgot-passwordPúblicaEnviar por e-mail um link de redefinição, válido por 60 minutos
• POST/api/auth/reset-passwordPúblicaDefinir uma senha nova com o token enviado por e-mail

Dois fatores e login#

Os dois fatores protegem o login por senha. Não valem para chaves de API, e é por isso que uma chave é a melhor credencial para trabalho não assistido.

• POST/api/2fa/enableJWTIniciar o cadastro: devolve o segredo, a URL do QR e os códigos de recuperação
• POST/api/2fa/verifyJWTConfirmar um código de seis dígitos e ligar os dois fatores
• POST/api/2fa/disableJWTDesligar os dois fatores
• POST/api/account/verification/requestJWTEnviar um link de verificação ao endereço logado
• GET/api/account/verification/confirm?token=PúblicaExibir a página de confirmação: não escreve nada
• POST/api/account/verification/confirmPúblicaEfetivar a verificação
• GET/api/auth/googlePúblicaIniciar login com Google
• GET/api/auth/google/callbackPúblicaRetorno do login com Google
• GET/api/auth/discordPúblicaIniciar login com Discord
• GET/api/auth/discord/callbackPúblicaRetorno do login com Discord

Preferências e avisos#

Chaves de e-mail e notificação, e o histórico de avisos da conta.

• GET/api/user/email-preferencesJWTEstado da inscrição em e-mails de marketing
• POST/api/user/email-preferencesJWTAlterar
• GET/api/user/notification-preferencesJWTPreferência de avisos de voto ao vivo
• POST/api/user/notification-preferencesJWTAlterar: precisa ser um booleano JSON de verdade
• GET/api/user/alerts?limit=20JWTAvisos da conta, do mais recente ao mais antigo, paginados por ?before
• POST/api/user/alerts/readJWTMarcar um aviso como lido
• POST/api/user/alerts/dismissJWTDispensar um aviso
• GET/api/email/unsubscribe?token=PúblicaCancelamento em um clique a partir de um token enviado por e-mail

Campanhas#

Criar campanhas, dirigi-las enquanto rodam e encerrá-las. É o coração da API de plataforma.

• GET/orders/getAllChave de APISuas campanhas, da mais recente à mais antiga, com o site junto
• GET/orders/get/{id}Chave de APIUma campanha
• POST/orders/checkoutChave de APICriar campanhas e cobrar do saldo
• POST/orders/updateChave de APIEditar uma campanha
• POST/orders/pauseChave de APIPausar uma campanha em andamento
• POST/orders/unpauseChave de APIRetomar uma campanha pausada
• POST/orders/archiveChave de APIArquivar uma campanha
• POST/orders/unarchiveChave de APIRestaurar uma campanha arquivada
• PATCH/orders/updateLimitChave de APIDefinir ou remover o teto diário de votos

POST /orders/checkout

O corpo é um array JSON de linhas de carrinho no nível superior, não um objeto. Cada linha é uma campanha. O carrinho inteiro é validado antes de qualquer cobrança, e a cobrança mais as inserções são uma única transação: um pedido acontece inteiro ou não acontece.

Uma linha de quantidade fixa

O caso comum: entregar um número definido de votos a uma URL.

curl -X POST "https://backend.toplistbot.com/orders/checkout?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": 9,
      "amount": 1000,
      "ownName": "https://arena-top100.com/index.php?a=in&u=yourserver",
      "custom_max_per_hour": 60
    }
  ]'

200 OK
Successfully purchased with token balance

Uma linha de assinatura

Para sites cujo indicador `subscribeable` vale 1. O preço vem do subscription_price_1d do site multiplicado pelos dias e pelo desconto do nível: Weekly é 0,90, Monthly é 0,80 e qualquer outro é 1,00. A quantidade entregue é derivada no servidor a partir do próprio subscription_speed do site, então nada do que você envia muda isso.

[
  {
    "type": "subscription",
    "website": { "id": 9 },
    "subscription_days": 30,
    "tier": { "name": "Monthly" },
    "url": "https://arena-top100.com/index.php?a=in&u=yourserver"
  }
]

Respostas

• 200Todas as linhas foram criadas e o saldo foi cobrado. O corpo é texto puro.
• 400O corpo não era JSON válido.
• 402Saldo insuficiente. A mensagem diz quantos tokens faltam e nada foi cobrado.
• 422Uma ou mais linhas estão erradas. Nada foi cobrado.
• 429O mesmo carrinho foi enviado nos últimos 60 segundos. Tente de novo após a espera indicada.

Um 422 aponta a linha problemática: os erros são indexados como items.[index].[field], então um carrinho com três linhas ruins se resolve numa ida e não em três.

{
  "errors": {
    "items.2.amount": ["Enter 0 or more votes; a negative amount is not allowed."]
  }
}

POST /orders/update

`id` é obrigatório; envie só os campos que está mudando. Pedidos de assinatura não podem ser modificados.

curl -X POST "https://backend.toplistbot.com/orders/update?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":184223,"amount_to_do":2000,"custom_name":"EU launch"}'

Teto diário

`type: "delete"` remove o teto. Nesse caso o validador ainda exige `max_votes_per_day`: mande qualquer inteiro.

curl -X PATCH "https://backend.toplistbot.com/orders/updateLimit?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":184223,"max_votes_per_day":500,"type":"set"}'

Registros e análises#

Dados de entrega, voto a voto e agregados. Leem um banco de registros separado e são mais lentos que o resto da API: consulte em minutos, não em segundos.

• GET/orders/logs/{id}Chave de APIRegistro de entrega voto a voto de uma campanha
• GET/orders/graph/{id}Chave de APISérie temporal de uma campanha, pronta para gráfico
• GET/api/orders/graph/summaryJWTUma série somando todas as suas campanhas
• GET/orders/grouped/usernames/{id}Chave de APIEntregas agrupadas pelo usuário que votou
• POST/orders/averageChave de APIEntrega média de várias campanhas
• GET/api/logs/{id}/filtered-graphJWTSérie temporal filtrada

Perfis de voto e proxy#

Um perfil de voto é uma lista nomeada de usuários com que a campanha vota. Um perfil de proxy é uma lista de países permitidos para os IPs usados. Vincule qualquer um deles a uma campanha com username_profile_id ou proxy_profile_id em /orders/update.

• GET/advanced/profile/getChave de APISeus perfis de voto
• GET/advanced/profile/get/{id}Chave de APIUm perfil de voto
• POST/advanced/profile/createChave de APICriar um perfil de voto, ou sobrescrever um por id
• DELETE/advanced/profile/delete/{id}Chave de APIExcluir um perfil de voto
• GET/advanced/profile/proxy/getChave de APISeus perfis de proxy
• GET/advanced/profile/proxy/get/{id}Chave de APIUm perfil de proxy
• POST/advanced/profile/proxy/createChave de APICriar um perfil de proxy, ou sobrescrever um por id
• DELETE/advanced/profile/proxy/delete/{id}Chave de APIExcluir um perfil de proxy

Tokens do Discord#

Para listas que autenticam votantes pelo Discord. Adicionar o mesmo token duas vezes é recusado como duplicata.

• GET/api/discord-tokensJWTSeus tokens do Discord
• POST/api/discord-tokensJWTAdicionar um token
• GET/api/discord-tokens/statsJWTUso acumulado dos seus tokens
• GET/api/discord-tokens/{id}JWTUm token
• PATCH/api/discord-tokens/{id}JWTAlterar um token ou seu estado ativo
• DELETE/api/discord-tokens/{id}JWTRemover um token
• PUT/api/discord-tokens/{id}/toggleJWTAlternar um token entre ativo e inativo

Cobrança e pagamentos#

Comprar tokens sempre termina numa página de pagamento hospedada, então recarregar não pode ser totalmente automático. Tudo depois da recarga pode.

• GET/invoices/getChave de APIHistórico de cobrança
• GET/api/subscriptions/subscriptionsJWTAssinaturas ativas
• GET/products/tokensByUserChave de APIPacotes de tokens com o preço da sua conta
• POST/company/getChave de APISeu endereço de cobrança
• POST/company/createChave de APIDefinir: country, region, city, address, postalCode
• GET/api/stripe/checkout?product_id=JWTUma URL do Stripe Checkout para um pacote de tokens
• GET/api/stripe/subscription?plan=JWTUma URL do Stripe Checkout para um plano
• GET/api/stripe/portalJWTUma URL do portal de cobrança do Stripe
• GET/api/stripe/documentsJWTFaturas e recibos do Stripe
• GET/coinpayments/checkoutChave de APIUma URL de pagamento em cripto

Carrinho salvo#

O carrinho do painel, guardado no servidor para sobreviver a uma troca de dispositivo. Você não precisa dele para fazer pedidos: /orders/checkout aceita o carrinho na própria requisição.

• GET/api/cartJWTO carrinho salvo
• PUT/api/cartJWTSubstituir
• POST/api/cartJWTSubstituir, igual ao PUT
• DELETE/api/cartJWTEsvaziar

Superfícies internas#

Existem para o Stripe, o agendador de tarefas e o desafio antiabuso do cadastro. São autenticadas por segredos compartilhados ou assinaturas e não fazem parte da superfície de integração: estão aqui só para o inventário ficar completo.

• POST/api/stripe/webhookEventos de pagamento do Stripe, autenticados por assinatura
• POST/api/jobs/tickExecuta as tarefas pendentes, autenticado por segredo compartilhado
• POST/api/pow/challengeDesafio de prova de trabalho do cadastro
• POST/api/logs/updateRastreador de atividade de e-mail
• POST/api/order/{email}Cria um pedido em outra conta: só para a lista de administradores
• GET/reset-password/{token}A antiga página de redefinição renderizada no servidor, mantida pelos links já enviados
• GET/PúblicaVerificação de saúde

O objeto site#

Devolvido por /orders/getAllWebsites e /orders/getWebsiteDetailsByName, e embutido em cada campanha como `website`.

Os campos omitidos aqui alimentam a interface do próprio painel. Leia se quiser, mas eles não fazem parte do contrato de integração e podem mudar sem aviso.

O objeto campanha#

Devolvido por /orders/getAll e /orders/get/. Repare no que falta: não existe campo de status.

Os campos omitidos aqui alimentam a interface do próprio painel. Leia se quiser, mas eles não fazem parte do contrato de integração e podem mudar sem aviso.

Está rodando? Já terminou?#

Uma campanha não tem campo de status, então você deduz o estado a partir de quatro colunas. Avalie estas condições em ordem e fique com a primeira que bater.

Progresso e reembolsos#

amount_to_do conta votos aceitos; amount_done conta envios. Só accept_rate por cento dos envios são aceitos, então as duas estão em unidades diferentes e subtrair uma da outra direto está errado.

// accept_rate arrives as a STRING, and it is per-site, not global.
const rate = Number(order.website.accept_rate)

// amount_done counts SUBMISSIONS; amount_to_do counts ACCEPTED votes.
// Convert before comparing them.
const delivered = order.amount_done * rate / 100
const remaining = Math.max(order.amount_to_do - delivered, 0)
const percent   = 100 * delivered / order.amount_to_do

// What cancelling right now would put back on your balance:
const refund    = (remaining / 1000) * order.website.price_per_1000

A mesma conta precifica um cancelamento: o reembolso é o restante não gasto ao preço de tabela do site, então dá para saber quanto vale parar uma campanha antes de decidir.