Interfejs programistyczny API serwisu Finser.pl umożliwia osobom trzecim tworzyć aplikację wykorzystujących zasoby i logikę serwisu. Jest to wersja tworzona w dość krótkim czasie, dlatego niektóre rozwiązania mogą odstawać od niektórych standardów.
Interfejs aplikacji znajduje się pod adresem api.finser.pl na porcie 80. Komunikacja odbywa się za pomocą protokołu HTTP, katalog wywołania ustala rodzaj żądania, dane natomiast przesyłane są metodą POST. Np.:
http://api.finser.pl/login/ http://api.finser.pl/get/ http://api.finser.pl/insert/
Każdy klient zobowiązany jest dołączyć do żądania w nagłówku parametr X-Finser-API z wartością wersji protokołu API. W przeciwnym wypadku nie uzyska dostępu.
User-Agent: Nazwa mojego klienta Accept-Encoding: gzip,deflate Accept: application/json, text/javascript, */* ... X-Finser-API: 0.5
Parametr User-Agent służy do identyfikacji klienta w celach statystycznych.
Komunikacja odbywa się tylko i wyłącznie za pomocą protokołu JSON. Każda odpowiedź serwera zwracana jest z nagłówkiem Content-type: application/json. Dlatego należy wybrać odpowiedni nagłówek Accept podczas żądania. Nie planuje się wprowadzić tzw. 'callbacku' dla aplikacji umieszczanych na stronach WWW.
Każde żądanie otrzymuje odpowiedź z odpowiednim kodem odpowiedzi. Kody są identyczne jak w standardzie HTTP:
200 OK 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 500 Internal Server Error
Niektóre żądania w przypadkach sukcesu, takiej jak logowanie czy dodawanie operacji nie zwracają żadnego rezultatu oprócz nagłówka 200 OK. Dlatego należy zwrócić szczególną uwagę na kody odpowiedzi.
Nagłówek 401 Unauthorized zwracany jest tylko i wyłącznie w przypadku gdy klient nie jest zalogowany.
Nagłówek 403 Forbidden zwracany w dwóch przypadkach: w przypadku utraty dostępu do niektórych części API (ban na dodawanie operacji albo ban na całą funkcjonalność API) albo przekroczenia limitów takich jak żądań danych (za dużo żądań w czasie) lub dodawania operacji (za duża ilość operacji w czasie).
Nagłówek 500 Internal Server Error może zostać zwrócony wraz z danymi HTML oraz innym nagłówkiem niż Content-type: application/json . Zaleca się nie obsługiwać w żaden sposób tej odpowiedzi oprócz komunikatu typu „błąd serwera”.
W niektórych przypadkach błędów, zwracana jest dodatkowa informacja w formacie JSON. Np.:
{
"error":"401",
"message":"Not logged in."
}
Logowanie odbywa się za pomocą wysłania dwóch zmiennych o nazwie username oraz password metodą typu POST pod http://api.finser.pl/login/. W przypadku sukcesu zostanie zwrócony kod 200 OK, w przypadku błędu typu złe hasło lub login, kod 401 Unauthorized. Nazwę użytkownika jak i hasło przesyłamy w czystym tekście.
Wraz z odpowiedzią otrzymamy tzw. ciasteczka z identyfikatorem sesji. Najbezpieczniej za każdym razem wysyłać wszystkie dostarczone przez serwer ciasteczka w każdym żądaniu. Dzisiaj klucz n_session trzyma identyfikator sesji. Może to ulec zmianie. Ciasteczka wysyłamy w nagłówku żądania, zgodnie ze specyfikacją HTTP.
Cookie: n_session=0c0d4bd89c3eb27c152a08c13e8e7c9a
Aby się wylogować wysyłamy żądanie bez żadnych zmiennych pod http://api.finser.pl/logout/. Po zakończeniu pracy klienta, nie ma obowiązku się wylogować. Choć jest to zalecane i mile widziane.
Aby dodać operację wysyłamy żądanie pod http://api.finser.pl/insert/ wraz ze zmienną text (w metodzie typu POST). Długość tekstu musi być nie dłuższe niż 255 znaków i nie krótsze niż 2. W przypadku dodania operacji zostanie zwrócony kod 200 OK, w przypadku błędów takich jak: niepoprawna nazwa konta, podana za duża kwota ( w momencie pisania tego tekstu limit jest ustalony na 1 miliard – 10000000) zostanie zwrócony błąd z kodem 400 Bad Request oraz dodatkowymi danymi w formacie JSON:
{
"error":"400",
"message":"Wrong account name."
}
Przy dodawaniu operacji nie ma możliwości zmiany czasu operacji na inny niż czas serwera lub czas serwera +/- ustawione w konfiguracji użytkownika przesunięcie czasu.
Aby zmienić czas dodawanej operacji musimy wraz z żądaniem oprócz zmiennej text wysłać zmienną time w formacie POSIX. Nie ważne w której strefie czasowej się znajdujemy, i tak wysyłamy czas UTC.
Należy pamiętać, że przeglądanie starszych operacji za pomocą API jest nie dostępne jak również poszczególne ich osuwanie (tylko ostatni wpis). Dlatego należy b. ostrożnie dodawać operacje. Nie należy zapomnieć o limicie operacji oraz wywołań.
Kasować możemy tylko ostatnią operację. Aby to zrobić wysyłamy żądanie bez żadnych zmiennych pod http://api.finser.pl/remove/ . W przypadku pomyślnego skasowania ostatniej operacji zostanie zwrócony kod 200 OK .
Przeglądanie operacji jest równoznaczne z poborem ostatnio dodanych operacji w ilości aktualnie zdefiniowanej przez konfigurację systemu (w momencie pisania tego tekstu to 16 operacji). Nie ma możliwości stronicowania operacji (czyli przeglądania starszych operacji).
Aby pobrać operacje, należy wysłać żądanie wraz ze zmienną query metodą POST pod http://api.finser.pl/get/. Zmienna query określa rodzaj zwracanych operacji:
| Wartość zmiennej query | Odpowiedź |
!last |
Ostatnio dodane operacje. |
#[nazwa tagu] (np. #kino) |
Ostatnio dodane operacje dla tagu #kino. |
$[nazwa konta] (np. $portfel) |
Ostatnio dodane operacje dla konta $portfel. |
Przykład danych zwracanych dla !last:
{
"query":"!last",
"operations": {
"933": {
"type":"m",
"time":"1278428492",
"text":"",
"value":"100.00 PLN",
"account_from":"$portfel",
"account_to":"$bank"
},
"932":{
"type":"a",
"time":"1278428140",
"text":"dosta\u0142em",
"value":"1.00 EUR",
"account":"$portfel"
}
}
}
Rodzaje operacji:
a – operacja dodanie, odjęcia kwoty m – operacja przeniesienia kwoty t – operacja transferu kwoty z jednej waluty do drugiej n – operacja notatka
Tag query zwraca nam nazwę naszego zapytania. W polu operations przesyłane są operacje sortowane od najnowszej do najstarszej operacji. Każdy element tego pola to numer rekordu w bazie Finsera danej operacji. Każda operacja ma pole type, time oraz text.
type – definiuje rodzaj operacji (składającej się z jednego znaku).
time – czas w formacie POSIX, czyli ilość sekund od 1 stycznia 1970, godz. 00:00:00, ustala czas operacji na liście (nie jest to czas dodania operacji, ale czas operacji w rozliczeniu). Czas jest bez strefowy (UTC), bez zmian na czas letni/zimowy.
text – treść operacji, może być pusta. Tekst należy sformatować pod względem wyszukania i zaznaczenia tagów. Operacji typu t oraz m nie parsujemy.
| Wyrażenie w pseudo kodzie | Wejście | Wyjście |
| #[a-zA-Z0-9_]+ | #tag | #tag |
| #[a-zA-Z0-9_[ZNAKI_POLSKIE]]+|[a-zA-Z0-9_]+ | #mamuśka|mama | #mamuśka* kierowany do #mama |
Każda operacja posiada również inne pola oprócz wyżej wymienionych:
| Typ operacji | Przykład operacji | Dodatkowe pola |
n |
$bank jakiś komentarz | account – nazwa konta z prefiksem '$', np. „$bank” |
a |
$bank wypłata +100 PLN $bank za przelew -1 EUR |
value – wartość kwoty z walutą, np. „ 100.00 PLN”, "-1.00 EUR"account – nazwa konta z prefiksem '$', np. „$bank” |
m |
$bank > $portfel wypłata w bankomacie 100 PLN | value – wartość kwoty przeniesionej z walutą, np. „ 100.00 PLN”account_from – nazwa konta skąd są pieniądze przenoszone z prefiksem '$', np. „$bank”account_to – nazwa konta do którego pieniądze trafiają z prefiksem '$', np. „$portfel” |
t |
$bank wymiana waluty 100 PLN > 25 EUR | value_from – wartość kwoty z której dokonaliśmy transferu wraz z walutą, np. „ -100.00 PLN”value_to – wartość kwoty do której dokonaliśmy transferu, np. „ 25.00 EUR”account – nazwa konta z prefiksem '$', np. „$bank” |
Kwoty są podawane w formacie z dwoma miejscami po przecinku. Znakiem przecinka jest kropka. Po kwocie występuje znak spacji oraz trzy znaki waluty. Aby pobrać samą wartość kwoty wystarczy wyciąć ostatnie cztery znaki.
W przypadku gdy query żąda konta lub tagu zwracane jest jeszcze jedno pole przed polem operations - summary. Przykład odpowiedzi:
{
"query":"#reszta",
"summary": {
"PLN":{
"plus":"8.44",
"minus":"0.00"
}
},
"operations": {
"764": {
"type":"a",
"time":"1277206190",
"text":"#reszta ze sklepu",
"value":"0.21 PLN",
"account":"$portfel"
},
"588": {
"type":"a",
"time":"1274799551",
"text":"Piotrek wzial moja #reszt\u0119|reszta :(",
"value":"-4.00 PLN",
"account":"$portfel"
}
}
}
Pole to pozwala wyznaczyć saldo tagu lub konta dla określonej waluty. Elementy pola to nazwy walut. Zwracane są tylko te elementy z określoną walutą które były użyte dla danego tagu/konta (np. jeżeli na koncie są środki w EUR i USD, zostaną zwrócone dwa elementy z tymi walutami). Aby obliczyć saldo tagu/konta należy wartość pole plus odjąć od wartości pola minus.
saldo = waluta.plus – waluta.minus
Może się zdarzyć, że wartość plus może być ujemna i analogicznie wartość minus może być ujemna (zwykle wynika to z braku zrozumienia idei Finsera w prowadzeniu rozliczenia).
W przypadków tagów (tylko i wyłącznie tagów) pole plus oznacza ilość łącznie przychodów dla danego tagu, natomiast pole minus łącznie wydatków dla danego tagu.
#kino bilet -100 zł #kino znalazłem +50 zł PLN.plus = 50.00 PLN.minus = 100.00 saldo = 50.00 – 100.00 = -50.00
W przypadku kont strona plus nie jest równoznaczna z wartością wydatków. Gdyś w przypadku przeniesień środków jak i transferu waluty właśnie strona plus jest zwiększana/zmniejszana.
Aby pobrać nazwy wszystkich kont razem z ich saldami wysyłamy żadanie http://api.finser.pl/accounts/ bez żadnych parametrów. Przykładowy wynik:
{
"6":{
"name":"$portfel",
"summary": {
"PLN":{
"plus":"2146.96",
"minus":"2098.94"
}
}
},
"7":{
"name":"$bank",
"summary":{
"PLN":{
"plus":"4222.47",
"minus":"3631.60"
}
}
}
}
Zasada obliczania salda kont, jest identyczna jak w przypadku punktu 06. W odpowiedzi zostają przesłane wszystkie konta użytkownika, nawet gdyby były puste (nie posiadały by ani jednej operacji).
Lista zmian tego dokumentu: