Dokumentace k API rozhraní služby eÚčty.cz - Beta verze
Ke službě eÚčty.cz je možné v omezené míře přistupovat i z jiných aplikací. Pokud máte zájem integrovat tuto službu do Vaší aplikace, můžete využít připraveného API rozhraní.
Základní informace
Důležité upozornění,jedná se o beta verzi API rozhraní, postupně dle Vašich reakcí a požadavků budou doplňovány další funkce, v případě závažných problémů se stávající funkce mohou změnit.
API jsou realizované technologií WEB SERVICE - protokoly SOAP, HTTP GET a HTTP Post.
Webové rozhraní služby je k dispozici na adrese
http://www.eucty.cz/api/apiservice.asmx
WSDL popis je k dispozici na adrese
http://www.eucty.cz/api/apiservice.asmx?wsdl
Podmínky využívání API rozhraní
Parametrem každé funkce je tzv. apiClientKey. Tento klíč by měl být unikátní pro
každou klientskou aplikaci využívající API rozhraní. Získáte ho napsáním žádosti
na info@eucty.cz .
Klíč může být dvojího typu, neveřejný a veřejný.
Neveřejný klíč se váže ke konkrétním uživatelským účtům (max. 10 účtů). Seznam uživatelských
jmen (userLogin) uveďte v žádosti o přiřazení klíče. API funkce s tímto klíčem je možné volat
pouze pro tyto uživatelské účty.
Veřejný klíč slouží pro aplikace určené Všem uživatelům. Aplikace pracující pod
veřejným klíčem musí splňovat
následující podmínky
- Aplikace musí být k dispozici pro všechny uživatele služby eÚčty
- Aplikace musí mít rozumnou úroveň zpracování
- O aplikaci musí být zveřejněna informace na stránkách služby eÚčty
- Aplikace musí být k dispozici zdarma, nebo je nutné dohodnout individuální podmínky
V praxi se pro vývoj používá neveřejný klíč, po dokončení aplikace se zažádá o veřejný
klíč (chcete-li nabídnou svou aplikaci pro ostatní uživatele).
Aplikace se musí chovat "mravně", zbytečně nezatěžovat server,
případné chyby v API se nesmí zneužívat, v opačném případě může být přístup
pod tímto klíčem zakázán.
Princip komunikace
Přesný popis metod, jejich parametrů a navratových hodnot je definován ve WSDL specifikaci
služby.
Každá metoda má následující parametry
apiClientKey:string - viz předchozí bod
userLogin:string -uživatelské jméno
userPassword:string - uživatelské heslo
Pokud jsou tyto parametry neplatné, vrací všechny metody exception (resp.
ResultIsOK na false,viz dále). Jedninou vyjímkou je metoda Testlogin.
Každá metoda vrací výsledek odvozený od třídy apiResult. Ta má následující členy.
ResultIsOk:boolean - true, pokud volání proběhlo správně, false
pokud nestala exception. V případě exception mají smysl následující 2 parametry.
ResultMessage:string - popis exception
ResultExceptionCode:long - kód chyby, některé chyby mají vlastní
kód, je možné jse specificky ošetřovat.
Poznámka: přestože technologie WEB SERVICE podporuje přímé generování exception,
není toto využíváno. Je nahrazeno tímto jednoduším mechanismem (apiResult) pro snadnější
zpracování. Po volání každé metody je tedy nutné zkontrolovat, zda je ResultIsOk
na true. Pokud ne, volání selhalo a je nutné se zachovat stejně, jako by byla generována
exception.
ResultExceptionCode
Public Const APIExCode_SystemException = 0
Public Const APIExCode_InvalidLogin = 1
Public Const APIExCode_InvalidApiClientKey = 3
Popis metod
V popisu metod nejsou uváděny 3 pevné parametry a v popisu návratových hodnot nejsou
uváděny parametry základní třídy apiResult
TestLogin
Vstupní parametry
Výstupní parametry
IsOk:boolean - platné/neplatné přihlašovací údaje
Message:string - hláška v případě neplatných údajů
Popis
Jako jediná metoda nevrací exception v případě neplatných přihlašovacích údajů či
klíče.
CurrencyList
Vstupní parametry
Výstupní parametry
Data:List(Of apiCurrency) - podrobné informace o podporovaných měnách
Popis
Stáhne seznam objektů apiCurrency. Ten obsahuje podrobné informace o všech podporovaných
měnách v systému, včetně Id měny
AccountList
Vstupní parametry
Výstupní parametry
Data:List(Of apiAccount) - podrobné informace o účtech
Popis
Stáhne seznam objektů apiAccount. Ten obsahuje podrobné informace o všech účtech,
na které má uživatel právo FullAccess nebo OnlyRead. Položka Amount není vyplněna
(viz následující funkce).
Enum enmUserAccountPermission
FullAccess = 0
OnlyRead = 1
Hidden = 2
End Enum
AccountListWithAmount
Vstupní parametry
Výstupní parametry
Data:List(Of apiAccount) - podrobné informace o účtech, včetně aktuálního stavu
na účtu (Amount)
Popis
Stáhne seznam objektů apiAccount. Ten obsahuje podrobné informace o všech účtech,
na které má uživatel právo FullAccess nebo OnlyRead. Na rozdíl od funkce AccountList
je vyplněna položka Amount - aktuální stav na účtu.
CategoryTree
Vstupní parametry
Výstupní parametry
Data:apiCategoryTree - stromová struktura kategorií
Popis
Vrátí stromovou strukturu kategorií (oblíbené i vše), včetně Id kategorie.
UserList
Vstupní parametry
Výstupní parametry
Data:List(Of apiUser) - seznam uživatelů v dané rodině
Popis
Stáhne seznam objektů apiUser.
AddTransaction
Vstupní parametry
Amount:single - Položka Amount musí být kladná pro
příjmy a záporná pro výdaje.
Description:string - popis transakce
Id_Account:Long - Id účtu
Id_Category:Long - Id kategorie
PaymentDate:DateTime - Datum zadání
Výstupní parametry
Data:apiTransaction - podrobné informace o vložené transakci (více údajů než v apiAddTransaction)
Popis
Vloží transakci, pokud se vložení podaří, vrátí skutečné údaje o vložené transakci.
Uživatel musí mít na účet právo FullAccess. Jako uživatele, který transakci provedl,
nastaví přihlášeného uživatele. Transakce je typu běžná transakce.
TransactionListLast50
Vstupní parametry
AccountId - účet který nás zajímá
Výstupní parametry
Data:List(Of apiTransaction) - seznam transakcí na tomto účtu.
Popis
Stáhne posledních 50 transakcí zadaných na tento účet