Documentație API

Prezentare generală

Toplistbot expune două API-uri HTTP. Ambele folosesc JSON peste HTTPS și consumă același sold de jetoane — alege-l pe cel potrivit modului tău de integrare.

API panou SMM

Un singur endpoint compatibil Perfect Panel. Dacă panoul tău vorbește deja protocolul SMM standard, îndreaptă-l aici și funcționează fără modificări de cod.

API platformă

API-ul REST din spatele panoului: parcurge catalogul de site-uri, autentifică-te și creează și administrează campanii din propria aplicație.

URL de bază

Base URL

https://backend.toplistbot.com/api

Primii pași

De la un cont nou la o campanie activă în cinci pași. Totul de mai jos folosește endpointul SMM, cea mai rapidă cale de intrare; API-ul platformei funcționează la fel odată ce ai un JWT.

Creează un cont
Înregistrează-te și confirmă-ți adresa de e-mail. Confirmarea îți adaugă 100 de jetoane gratuite în sold, suficient pentru o campanie reală înainte să cheltui ceva.
Copiază-ți cheia API
Deschide panoul și generează o cheie API. Tratează-o ca pe o parolă — consumă din soldul tău de jetoane. O poți regenera oricând, iar cea veche devine imediat invalidă.
3
Găsește serviciul dorit
Listează toate site-urile pe care poți plasa comenzi. Fiecare intrare are un id numeric de serviciu și un tarif în jetoane la 1.000 de acțiuni. Notează id-ul site-ului pe care vrei să promovezi.
cURL
```
curl -X POST https://backend.toplistbot.com/api/v2 -d "key=YOUR_API_KEY" -d "action=services"
```

Plasează prima comandă

Trimite id-ul serviciului, URL-ul pe care rulează campania și câte acțiuni să execute. Costul se deduce imediat, iar răspunsul îți dă un id de comandă.

cURL

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"

5
Urmărește livrarea
Interoghează id-ul comenzii pentru a vedea cât s-a livrat. Când ești mulțumit de flux, conectează aceleași apeluri în propriul panou sau în scripturile tale.
cURL
```
curl -X POST https://backend.toplistbot.com/api/v2 -d "key=YOUR_API_KEY" -d "action=status" -d "orders=184223"
```

Conectarea unei instanțe Perfect Panel

Dacă folosești Perfect Panel sau software compatibil de panou SMM, nu trebuie să scrii cod — adaugă Toplistbot ca furnizor cu setările de mai jos și importă lista de servicii.

URL API: https://backend.toplistbot.com/api/v2
Cheie API: YOUR_API_KEY
Metodă HTTP: POST

Începe cu o cantitate mică pe un singur site, ca să confirmi că formatul linkului este acceptat, înainte să crești volumul. Un link greșit consumă tot jetoane.

Autentificare

Cele două API-uri se autentifică diferit. Endpointul SMM folosește o cheie API de durată lungă; API-ul platformei folosește un JWT obținut la autentificare.

Cheie API (endpoint SMM)

Trimite cheia ca un câmp `key` la fiecare cerere — ca text de formular, parametru de interogare sau antet `Authorization: Bearer`. O generezi și o regenerezi din panou. Un GET către același endpoint returnează starea ok și este o metodă ieftină de a verifica dacă o cheie este validă.

Health check

curl https://backend.toplistbot.com/api/v2?key=YOUR_API_KEY

JWT (API platformă)

Autentifică-te pentru a primi un token, apoi trimite-l ca bearer token pe rutele care necesită autentificare. Tokenurile expiră — apelează /auth/refresh pentru unul nou.

curl -X POST https://backend.toplistbot.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"..."}'

Authenticated request

curl https://backend.toplistbot.com/api/orders/getAll \
  -H "Authorization: Bearer YOUR_JWT"

Cheia API consumă sold real de jetoane. Păstreaz-o pe server: orice ajunge în browser sau este comis într-un repository trebuie considerat compromis și regenerat din panou.

Jetoane și prețuri

Campaniile se plătesc în jetoane, cumpărate în avans. Fiecare site publică un tarif — câte jetoane costă 1.000 de acțiuni de campanie acolo — returnat ca `rate` de acțiunea services.

Cost formula

cost_in_tokens = (rate * quantity) / 1000

Un site cu tariful 13 costă 13 jetoane pentru 1.000 de acțiuni, deci o comandă de 500 costă 6,5 jetoane. Costul se deduce la acceptarea comenzii, iar anularea returnează restul necheltuit.

Răspunsurile balance și status raportează un câmp de monedă USD pentru compatibilitate cu Perfect Panel, dar valoarea este un sold de jetoane, nu dolari. Tratează numărul ca jetoane.

API panou SMM

Un singur endpoint face totul. Trimite un câmp `action` cu fiecare POST pentru a alege operațiunea; fiecare cerere include și `key`.

POSThttps://backend.toplistbot.com/api/v2

Acțiune	Parametri
`services`	—
`add`	service, link, quantity, interval?
`status`	orders
`balance`	—
`cancel`	orders

`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

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

Response

[
  {
    "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.

Parametru	Tip	Descriere
`key`obligatoriu	string	Cheia ta API.
`action`obligatoriu	string	Trebuie să fie `add`.
`service`obligatoriu	integer	Id-ul serviciului din acțiunea services.
`link`obligatoriu	url	URL-ul pe care rulează campania. Trebuie să fie un URL valid.
`quantity`obligatoriu	integer	Numărul de acțiuni de executat, între 1 și 50000.
`interval`	integer	Acțiuni pe oră. Implicit 15, plafonat la 4000, și nu poate depăși maximul propriu al site-ului.

cURL

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"

Response

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

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

Response — single order

{
  "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.

Response — multiple orders

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

`action=balance`

Returnează soldul rămas de jetoane.

cURL

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

Response

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

`action=cancel`

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

cURL

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

Response

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

API platformă

Același API REST folosit de panou. Endpointurile de catalog sunt publice; restul necesită un JWT.

Catalog

Public, fără autentificare. Util pentru a-ți construi propriul director sau propria pagină de prețuri.

GET/orders/getAllWebsitesToate site-urile listate, cu tarife și metadate
POST/orders/getWebsiteDetailsByNameUn site după numele exact
GET/orders/getAllBasicWebsitesDetails20 de nume de site-uri aleatorii
POST/products/getSuggestionsSite-uri similare pentru un set de id-uri
GET/products/tokensPachetele de jetoane disponibile
POST/products/suggestPropune un site pe care să îl adăugăm
GET/news/timelineJurnalul de modificări al produsului

cURL

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

Cont

Înregistrare, sesiuni și istoric de facturare.

POST/auth/registerCreează un cont
POST/auth/loginSchimbă datele de acces pe un JWT
POST/auth/refreshEmite un JWT nou JWT
POST/auth/logoutInvalidează JWT-ul curent JWT
GET/auth/user-profileProfilul utilizatorului curent JWT
POST/auth/reset-api-keyRegenerează cheia API JWT
GET/invoices/getIstoric de facturare JWT

Campanii

Creează și administrează campanii și citește jurnalele de livrare.

GET/orders/getAllCampaniile tale, cele mai noi întâi
POST/orders/checkoutCreează una sau mai multe campanii
POST/orders/updateEditează o campanie
POST/orders/pausePune pe pauză o campanie activă
POST/orders/unpauseReia o campanie pusă pe pauză
POST/orders/archiveArhivează o campanie
PATCH/orders/updateLimitModifică plafonul zilnic
GET/orders/logs/{id}Jurnalul de livrare al unei campanii
GET/orders/graph/{id}Serie temporală pentru grafice

Erori

Erorile vin cu un status HTTP corespunzător. Erorile de validare returnează un obiect `errors` indexat după numele câmpului.

400Acțiune invalidă, parametri incorecți sau un id de serviciu inexistent.
401Date de autentificare lipsă sau invalide.
403Autentificat, dar soldul de jetoane este prea mic pentru comandă.
422Cererea a fost înțeleasă, dar nu a trecut validarea.

Validation error

{
  "errors": {
    "quantity": ["The quantity must be at least 1."]
  }
}

Limite și observații

Cantitatea comenzii trebuie să fie între 1 și 50000 de acțiuni.
Intervalul este implicit 15 pe oră și este plafonat la 4000. Solicitarea unei valori peste maximul site-ului este respinsă cu un 400 care indică limita.
Acțiunile `refill` și `refill_status` nu sunt implementate — creează în schimb o comandă nouă.
Câmpul `status` nu este încă un semnal de progres în timp real; folosește `remains` și `start_count` pentru a urmări livrarea.
Site-urile de listare își stabilesc propriile reguli și le schimbă în timp. Ești responsabil să te asiguri că utilizarea ta respectă termenii oricărui site pe care promovezi. Nu promitem o anumită poziție sau clasare.

Întreabă-ne pe Discord

Prezentare generală

API panou SMM

API platformă

URL de bază

Primii pași

Creează un cont

Copiază-ți cheia API

Găsește serviciul dorit

Plasează prima comandă

Urmărește livrarea

Conectarea unei instanțe Perfect Panel

Autentificare

Cheie API (endpoint SMM)

JWT (API platformă)

Jetoane și prețuri

API panou SMM

action=services

action=add

action=status

action=balance

action=cancel

API platformă

Catalog

Cont

Campanii

Erori

Limite și observații

Începe promovarea acum!

`action=services`

`action=add`

`action=status`

`action=balance`

`action=cancel`