Documentație API

action=services

Listează toate site-urile pe care poți comanda, cu tariful curent și limitele. Folosește id-ul `service` în apelurile 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` este în jetoane la 1.000 de acțiuni. `min` este 1 și `max` este 50000 pentru fiecare serviciu.

action=add

Creează o campanie și îi deduce imediat costul din soldul tău.

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

Returnează progresul pentru una sau mai multe comenzi. Trimite un singur id pentru un obiect simplu sau o listă separată prin virgulă.

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"
}

Cu mai multe id-uri, răspunsul este indexat după id-ul comenzii, iar comenzile necunoscute sau care nu îți aparțin returnează o intrare de eroare în loc să pice întreaga cerere.

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

`status` și `cancel` acceptă cel mult 100 de id-uri de comandă per apel. Grupează în loc să iterezi: un apel cu 100 de id-uri este mult mai ieftin pentru ambele părți decât 100 de apeluri.

action=balance

Returnează soldul rămas de jetoane.

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

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

action=cancel

Oprește o comandă și returnează restul necheltuit în sold. Comenzile finalizate nu pot fi anulate.

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" } }
]

Catalog și descoperire#

Public, fără credențial. getAllWebsites este endpoint-ul de la care pornești: aduce id-ul, prețul, plafonul orar și rata de acceptare de care ai nevoie ca să calculezi prețul și să dimensionezi o comandă.

• GET/orders/getAllWebsitesPublicăCatalogul complet: fiecare site cu tarife, limite și metadate
• GET/orders/getAllBasicWebsitesDetailsPublică20 de nume de site la întâmplare, pentru widget-uri și autocompletare
• POST/orders/getWebsiteDetailsByNamePublicăUn site după numele exact
• POST/products/getSuggestionsPublicăSite-uri înrudite cu un set de id-uri
• GET/products/demand?days=30PublicăCât de mult a fost comandat fiecare site recent
• GET/products/tokensPublicăPachete de token-uri pe care le poți cumpăra
• POST/products/suggestCheie APICere-ne să adăugăm un site nou
• GET/api/news/timelinePublicăJurnalul de noutăți al produsului

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

Cere mai puțin

Catalogul întreg are în jur de 665 KB pentru 396 de site-uri, iar două câmpuri cu care nu vei comanda niciodată reprezintă jumătate din el: un bloc JSON de popularitate și descrierea de marketing. Păstrează doar câmpurile cu care comanzi și renunță la site-urile inactive și ajunge la circa 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}]'

Cont și sesiuni#

Înregistrarea are nevoie de browser: este protejată de o provocare Cloudflare. Înregistrează-te o dată pe app.toplistbot.com, apoi automatizează tot ce urmează.

• POST/api/auth/registerPublicăCreare cont: doar din browser, protejat de captcha
• POST/api/auth/loginPublicăSchimbă credențialele pe un JWT
• POST/api/auth/refreshJWTEmite un JWT nou dintr-unul care expiră
• POST/api/auth/logoutJWTInvalidează JWT-ul curent
• GET/api/auth/user-profileJWTContul autentificat, cu sold și cheie API
• GET/api/userJWTAcelași obiect de utilizator, pe o cale mai scurtă
• GET/api/api_tokenCheie APIRezolvă o cheie API către proprietarul ei: folosește-l ca să validezi o cheie
• POST/api/auth/reset-api-keyJWTRotește cheia API; cea veche moare imediat
• POST/api/auth/fingerprintJWTÎnregistrează o amprentă de browser pe cont
• POST/api/auth/ipJWTÎnregistrează IP-ul curent al contului
• POST/api/auth/forgot-passwordPublicăTrimite pe e-mail un link de resetare, valabil 60 de minute
• POST/api/auth/reset-passwordPublicăSetează o parolă nouă cu token-ul primit pe e-mail

Doi factori și autentificare#

Doi factori protejează autentificarea cu parolă. Nu se aplică cheilor API, motiv pentru care o cheie este credențialul mai bun pentru lucrul nesupravegheat.

• POST/api/2fa/enableJWTPornește înrolarea: întoarce secretul, URL-ul QR și codurile de recuperare
• POST/api/2fa/verifyJWTConfirmă un cod de șase cifre și activează cei doi factori
• POST/api/2fa/disableJWTDezactivează cei doi factori
• POST/api/account/verification/requestJWTTrimite un link de verificare la adresa autentificată
• GET/api/account/verification/confirm?token=PublicăAfișează pagina de confirmare: nu scrie nimic
• POST/api/account/verification/confirmPublicăFinalizează verificarea
• GET/api/auth/googlePublicăPornește autentificarea Google
• GET/api/auth/google/callbackPublicăRevenirea de la autentificarea Google
• GET/api/auth/discordPublicăPornește autentificarea Discord
• GET/api/auth/discord/callbackPublicăRevenirea de la autentificarea Discord

Preferințe și alerte#

Comutatoarele de e-mail și notificări, plus fluxul de alerte al contului.

• GET/api/user/email-preferencesJWTStarea abonării la e-mailuri de marketing
• POST/api/user/email-preferencesJWTSchimb-o
• GET/api/user/notification-preferencesJWTPreferința pentru notificările de vot în timp real
• POST/api/user/notification-preferencesJWTSchimb-o: trebuie să fie un boolean JSON adevărat
• GET/api/user/alerts?limit=20JWTAlertele contului, de la cea mai nouă, paginate cu ?before
• POST/api/user/alerts/readJWTMarchează o alertă ca citită
• POST/api/user/alerts/dismissJWTÎnchide o alertă
• GET/api/email/unsubscribe?token=PublicăDezabonare într-un clic dintr-un token trimis pe e-mail

Campanii#

Creează campanii, condu-le în timp ce rulează și încheie-le. Este nucleul API-ului platformei.

• GET/orders/getAllCheie APICampaniile tale, de la cea mai nouă, cu site-ul atașat
• GET/orders/get/{id}Cheie APIO campanie
• POST/orders/checkoutCheie APICreează campanii și scade din sold
• POST/orders/updateCheie APIEditează o campanie
• POST/orders/pauseCheie APIPune pe pauză o campanie activă
• POST/orders/unpauseCheie APIReia o campanie pusă pe pauză
• POST/orders/archiveCheie APIArhivează o campanie
• POST/orders/unarchiveCheie APIRestaurează o campanie arhivată
• PATCH/orders/updateLimitCheie APISetează sau șterge plafonul zilnic de voturi

POST /orders/checkout

Corpul este un array JSON de linii de coș la nivelul cel mai de sus, nu un obiect. Fiecare linie este o campanie. Tot coșul este validat înainte să se scadă ceva, iar scăderea și inserările sunt o singură tranzacție: o comandă se întâmplă complet sau deloc.

O linie cu cantitate fixă

Cazul obișnuit: livrarea unui număr stabilit de voturi către un 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

O linie de abonament

Pentru site-urile al căror indicator `subscribeable` este 1. Prețul vine din subscription_price_1d al site-ului înmulțit cu numărul de zile și cu reducerea nivelului: Weekly este 0,90, Monthly este 0,80, orice altceva 1,00. Cantitatea livrată este derivată pe server din propriul subscription_speed al site-ului, deci nimic din ce trimiți nu o schimbă.

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

Răspunsuri

• 200Toate liniile au fost create și soldul a fost debitat. Corpul este text simplu.
• 400Corpul nu era JSON valid.
• 402Token-uri insuficiente. Mesajul spune câte lipsesc și nu s-a debitat nimic.
• 422Una sau mai multe linii sunt greșite. Nu s-a debitat nimic.
• 429Același coș a fost trimis în ultimele 60 de secunde. Reîncearcă după așteptarea indicată.

Un 422 numește linia problematică: erorile sunt indexate ca items.[index].[field], deci un coș cu trei linii greșite se repară dintr-un singur drum, nu din trei.

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

POST /orders/update

`id` este obligatoriu; trimite doar câmpurile pe care le schimbi. Comenzile de abonament nu pot fi modificate.

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"}'

Plafon zilnic

`type: "delete"` șterge plafonul. Validatorul cere în continuare `max_votes_per_day` în acest caz: trimite orice număr întreg.

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"}'

Jurnale și analize#

Date de livrare, vot cu vot și agregate. Citesc o bază de date de jurnale separată și sunt mai lente decât restul API-ului: interoghează-le la minute, nu la secunde.

• GET/orders/logs/{id}Cheie APIJurnalul de livrare vot cu vot al unei campanii
• GET/orders/graph/{id}Cheie APISerie temporală pentru o campanie, gata de grafic
• GET/api/orders/graph/summaryJWTO serie pentru toate campaniile tale
• GET/orders/grouped/usernames/{id}Cheie APILivrări grupate după utilizatorul care a votat
• POST/orders/averageCheie APILivrarea medie pentru mai multe campanii
• GET/api/logs/{id}/filtered-graphJWTSerie temporală filtrată

Profiluri de vot și proxy#

Un profil de vot este o listă denumită de utilizatori cu care votează o campanie. Un profil de proxy este o listă de țări permise pentru IP-urile folosite. Atașează oricare unei campanii cu username_profile_id sau proxy_profile_id în /orders/update.

• GET/advanced/profile/getCheie APIProfilurile tale de vot
• GET/advanced/profile/get/{id}Cheie APIUn profil de vot
• POST/advanced/profile/createCheie APICreează un profil de vot sau suprascrie unul după id
• DELETE/advanced/profile/delete/{id}Cheie APIȘterge un profil de vot
• GET/advanced/profile/proxy/getCheie APIProfilurile tale de proxy
• GET/advanced/profile/proxy/get/{id}Cheie APIUn profil de proxy
• POST/advanced/profile/proxy/createCheie APICreează un profil de proxy sau suprascrie unul după id
• DELETE/advanced/profile/proxy/delete/{id}Cheie APIȘterge un profil de proxy

Token-uri Discord#

Pentru topurile care autentifică votanții prin Discord. Adăugarea aceluiași token de două ori este respinsă ca duplicat.

• GET/api/discord-tokensJWTToken-urile tale Discord
• POST/api/discord-tokensJWTAdaugă un token
• GET/api/discord-tokens/statsJWTUtilizarea cumulată a token-urilor tale
• GET/api/discord-tokens/{id}JWTUn token
• PATCH/api/discord-tokens/{id}JWTSchimbă un token sau starea lui activă
• DELETE/api/discord-tokens/{id}JWTElimină un token
• PUT/api/discord-tokens/{id}/toggleJWTComută un token între activ și inactiv

Facturare și plăți#

Cumpărarea de token-uri se termină mereu pe o pagină de plată găzduită, deci alimentarea nu poate fi complet automată. Tot ce urmează după alimentare poate fi.

• GET/invoices/getCheie APIIstoricul facturării
• GET/api/subscriptions/subscriptionsJWTAbonamente active
• GET/products/tokensByUserCheie APIPachete de token-uri la prețul contului tău
• POST/company/getCheie APIAdresa ta de facturare
• POST/company/createCheie APISetează-o: country, region, city, address, postalCode
• GET/api/stripe/checkout?product_id=JWTUn URL Stripe Checkout pentru un pachet de token-uri
• GET/api/stripe/subscription?plan=JWTUn URL Stripe Checkout pentru un plan
• GET/api/stripe/portalJWTUn URL către portalul de facturare Stripe
• GET/api/stripe/documentsJWTFacturi și chitanțe Stripe
• GET/coinpayments/checkoutCheie APIUn URL de plată în cripto

Coș salvat#

Coșul panoului, păstrat pe server ca să supraviețuiască unei schimbări de dispozitiv. Nu îți trebuie ca să plasezi comenzi: /orders/checkout primește coșul direct în cerere.

• GET/api/cartJWTCoșul salvat
• PUT/api/cartJWTÎnlocuiește-l
• POST/api/cartJWTÎnlocuiește-l, la fel ca PUT
• DELETE/api/cartJWTGolește-l

Suprafețe interne#

Există pentru Stripe, planificatorul de sarcini și provocarea antiabuz de la înregistrare. Sunt autentificate prin secrete partajate sau semnături și nu fac parte din suprafața de integrare: sunt listate aici doar ca inventarul să fie complet.

• POST/api/stripe/webhookEvenimente de plată Stripe, autentificate prin semnătură
• POST/api/jobs/tickRulează sarcinile scadente, autentificat prin secret partajat
• POST/api/pow/challengeProvocarea proof-of-work de la înregistrare
• POST/api/logs/updateUrmărirea activității de e-mail
• POST/api/order/{email}Plasează o comandă pe alt cont — doar pentru lista de administratori
• GET/reset-password/{token}Vechea pagină de resetare randată pe server, păstrată pentru linkurile deja trimise
• GET/PublicăVerificare de stare

Obiectul site#

Întors de /orders/getAllWebsites și /orders/getWebsiteDetailsByName, și inclus în fiecare campanie sub `website`.

Câmpurile omise aici alimentează interfața panoului. Citește-le dacă vrei, dar nu fac parte din contractul de integrare și se pot schimba fără anunț.

Obiectul campanie#

Întors de /orders/getAll și /orders/get/. Observă ce lipsește: nu există un câmp de stare.

Câmpurile omise aici alimentează interfața panoului. Citește-le dacă vrei, dar nu fac parte din contractul de integrare și se pot schimba fără anunț.

Rulează? S-a terminat?#

O campanie nu are câmp de stare, deci o deduci din patru coloane. Evaluează condițiile în ordine și oprește-te la prima potrivire.

Progres și rambursări#

amount_to_do numără voturi acceptate; amount_done numără trimiteri. Doar accept_rate la sută dintre trimiteri sunt acceptate, deci cele două sunt în unități diferite și scăderea directă a uneia din cealaltă este greșită.

// 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

Același calcul dă prețul unei anulări: rambursarea este restul necheltuit la prețul de listă al site-ului, așa că poți afla cât valorează oprirea unei campanii înainte să te decizi.