Klientų sistemos API

Prisijungimas prie API

Klientų sistemos programavimo sąsaja (API) skirta veiksmų su paslaugomis automatizavimui bei integravimui į trečųjų šalių sistemas. Prisijungimas prie API vyksta per HTTPS protokolą, rezultatai grąžinami JSON formatu.

Užklausos formatas:

https://api.iv.lt/json.php
?nick=<prisijungimo vardas>
&password=<slaptažodis>
&command=<komanda>
&id=<paslaugos id>
&...=<kiti parametrai>

Parametrų paaiškinimai:

• prisijungimo vardas - specialaus API naudotojo vardas
• slaptažodis - specialaus API naudotojo slaptažodis
• komanda - komanda vykdymui, pvz., "version" arba "account_info"
• id - paslaugos ID, kurį galite rasti per klientų sistemą paslaugos valdymo puslapyje, arba per API paslaugų sąraše
• kiti parametrai - papildomi parametrai, priklausomai nuo konkrečios komandos

SVARBU! Prisijungimas prie API galimas tik iš IV potinklių, t.y. iš pas mus talpinamų serverių. API šiuo metu yra beta stadijos, todėl gali pasitaikyti tam tikrų klaidų, komandų ir resultatų formatas laikui bėgant gali keistis, iki 1.0 versijos šis puslapis bus vieninteliu informacijos apie naudojimasi API šaltiniu. Papildoma techninė pagalba API klausimais šiuo metu nėra teikiama.

Specialus API naudotojas

Norėdami jungtis prie klientų sistemos per API, turėsite sukurti specialų API naudotoją. Tam klientų sistemoje apsilankykite naudotojų tvarkymo puslapyje:

https://klientams.iv.lt/users.php

Ir sukurkite papildomą naudotoją su aprašymu "API" (be kabučių). Su šio naudotojo prisijungimo duomenimis galėsite jungtis prie API, tačiau ne prie klientų sistemos.

Klaidų apdorojimas

Nesant galimybei įvykdyti užklausos, API grąžina vieną iš standartinių HTTP klaidų:

• 400 - nurodyti klaidingi parametrai arba komanda.
• 401 - neteisingi prisijungimo duomenys arba naudotojas neturi "API" aprašo.
• 403 - užklausa gauta nešifruotu HTTPS protokolu, arba ne iš IV tinklui priklausančio IP adreso.

Apribojimai

Siekiant užtikrinti patikimą API veikimą, vienam naudotojui leidžiama siųsti ne daugiau kaip 100 užklausų per minutę.

Saugumo sumetimais iš to paties IP leidžiama ne daugiau kaip 100 klaidingų užklausų per parą. Viršijus šį limitą prisijungimai nebebus leidžiami.

API naudojimo pavyzdys

Trumpas PHP kodo pavyzdys, iliustruojantis naudojimąsi API:

$nick = "prisijungimo vardas";
$password = "slaptažodis";
$server_id = "serverio paslaugos ID";
$api_url = "https://api.iv.lt/json.php?nick=$nick&password=$password&command=";

$account = json_decode(file_get_contents($api_url."account_info"));
$bonuses = json_decode(file_get_contents($api_url."account_bonuses&count=100"));

print_r($account); // atspausdina informaciją apie kliento paskyrą
print_r($bonuses); // atspausdina informaciją apie kliento paskutines gautas premijas (max 100)

file_get_contents($api_url."server_reboot&id=$server_id"); // perkrauna serverį

API komandos

Bendros paskyros komandos

version

Parametrų nėra.

Rezultatas:

• API versijos numeris.

account_info

Parametrų nėra.

Rezultatas:

• Kliento paskyros informacija, kartu su permokos ir premijos likučiu.

account_orders

Parametrų nėra.

Rezultatas:

• Išrašytų sąskaitų sąrašas, kartu su apmokėjimo būsena, suma, nuoroda spausdinimui.

account_services

Parametrų nėra.

Rezultatas:

• Aktyvuotų paslaugų sąrašas, su galiojimo datom, kainom, pavadinimais.

account_credits

Parametrai:

• count - kiek paskutinių įrašų grąžinti (max 1000).

Rezultatas:

• Pridėtų ir panaudotų permokų išrašas.

account_bonuses

Parametrai:

• count - kiek paskutinių įrašų grąžinti (max 1000).

Rezultatas:

• Pridėtų ir panaudotų premijų išrašas su detalia informacija (SMS turinys, paslaugos pavadinimas).

Dedikuoto serverio valdymo komandos

server_info

Parametrai:

• id - paslaugos ID.

Rezultatas:

• Informacija apie serverį, serverio resursų (RAM, HDD) sunaudojimą (atnaujinama kas 1 val.)

server_tasks

Parametrai:

• id - paslaugos ID.
• task_id - užduoties ID (neprivalomas).
• task - užduoties pavadinimas (neprivalomas).
• count - kiek paskutinių įrašų grąžinti (max 1000).

Rezultatas:

• Informacija apie vykdomas arba įvykdytas serverio užduotis (pvz., perkrovimas).

server_graphs

Parametrai:

• id - paslaugos ID.
• width - grafikų plotis pikseliais (max 1000).
• ip - naudotojo IP, iš kurio bus peržiūrimi grafikai.

Rezultatas:

• Nuorodos į serverio grafikus (tinklo, CPU, RAM ir kt.)

server_os

Parametrai:

• id - paslaugos ID.

Rezultatas:

• Sąrašas operacinių sistemų, kurias galima įdiegti į serverį.

server_reboot

Parametrai:

• id - paslaugos ID.

Rezultatas:

• task_id - užduoties ID, pagal kurį galima sekti užduoties vykdymo būklę.

server_recreate

Parametrai:

• id - paslaugos ID.
• os - operacinės sistemos ID (pvz., centos-6-x86_64).

Rezultatas:

• task_id - užduoties ID, pagal kurį galima sekti užduoties vykdymo būklę.

server_reset_password

Parametrai:

• id - paslaugos ID.

Rezultatas:

• task_id - užduoties ID, pagal kurį galima sekti užduoties vykdymo būklę.

server_change

Parametrai:

• id - paslaugos ID.
• cpu - procesorius GHz (2..16)
• ram - atmintis MB (2048..16384)
• quota - disko vieta GB (20..800)
• bandwidth - pralaidumas Mbps (20..400)

Rezultatas:

• task_id - užduoties ID, pagal kurį galima sekti užduoties vykdymo būklę.

server_domain

Parametrai:

• id - paslaugos ID.
• domain - naujas serverio hostname.

Rezultatas:

• task_id - užduoties ID, pagal kurį galima sekti užduoties vykdymo būklę.