Kontomierz API
Wprowadzenie
Oddajemy w Twoje ręce proste i nowoczesne API, abyś mógł używać Kontomierza na swoich warunkach. W oparciu o to API powstały już dwie aplikacje - klient na iPhone'a i na Androida. Zachęcamy do zabawy!
Zarys techniczny:
- HTTPS RESTful API
- Odpowiedzi w JSON lub XML do wyboru - obie wersje działają równolegle
- Bezsesyjne, oparte o klucz API
Konwencje
GET POST PUT DELETE | to metody HTTP, których musisz użyć, aby wygenerować poprawne żądanie zgodnie z konwencją REST. Jeśli Twoja biblioteka nie umożliwia ustawienia metod PUT i DELETE, możesz je zasymulować poprzez dodatkowy parametr _method o wartości "put" lub "delete" (z małych liter). |
---|---|
:format | format odpowiedzi. Możliwe wartości to "xml" i "json". Każdy URL musi być zakończony rozszerzeniem .xml lub .json |
:id | identyfikator obiektu, którego dotyczy żądanie |
200 | status zwracany w przypadku pomyślnej odpowiedzi (lista/szczegóły obiektu, aktualizacja obiektu, usunięcie obiektu) |
201 | status zwracany w przypadku pomyślnego utworzenia obiektu |
422 | status zwracany w przypadku nieprawidłowych parametrów przy tworzeniu lub aktualizacji obiektu (np. gdy pole liczbowe zawiera tekst lub brakuje obowiązkowego parametru) |
401 | brak autoryzacji (np. nieprawidłowy login, hasło lub klucz API) |
Rejestracja nowego użytkownika
API pozwala dodać nowego użytkownika do Kontomierza. Sama aktywacja musi jednak nastąpić klasycznie, czyli poprzez kliknięcie w link wysłany e-mailem.
Parametry:
user[email] | adres mailowy użytkownika, na który zostanie wysłany link aktywacyjny. W klientach mobilnych warto ustawić klawiaturę dedykowaną wpisywaniu e-maila (widoczny symbol małpy @ i ukryte niepotrzebne znaki). Opcjonalnie można walidować e-maila po stronie klienta. Parametr obowiązkowy. |
---|---|
user[password] | hasło użytkownika. Parametr obowiązkowy. |
user[password_confirmation] | powtórzenie hasła użytkownika. Musi być identyczne z password. opcjonalnie można to walidować po stronie klienta. Parametr obowiązkowy. |
user[terms_of_service] | "checkbox" określający czy użytkownik zaakceptował regulamin. Dozwolone wartości to "1" jeśli regulamin został zaakceptowany i "0" w przeciwnym wypadku; Parametr obowiązkowy. |
Odpowiedź po pomyślnej rejestracji: 201
api_key | klucz API |
---|
Odpowiedź po błędzie: 422
errors | słownik błędów na poszczególnych polach, np. { "errors": { "email": ["- niepoprawny adres e-mail"] } } |
---|
Uwierzytelnienie kluczem API
API jest bezsesyjne. Każde żądanie jest uwierzytelniane niezależnie kluczem API. Klient nie powinien wysyłać żadnych ciastek.
Klucz API należy dołączać do każdego żądania jako parametr o nazwie api_key.
Klucz API jest na stałe przypisany do użytkownika i nadaje się do zapamiętania na urządzeniach osobistych (np. smartphone'ach), do których inne osoby nie mają dostępu.
Klucz API daje dostęp tylko do wybranych usług aplikacji (opisanych w niniejszej dokumentacji). W szczególności - w przeciwieństwie pełnego emaila i hasła - nie daje możliwości odczytania z serwera klucza deszyfrującego hasła do banków.
Skąd wziąć klucz API?
Klucz API można uzyskać logując się do aplikacji. Należy podać email i hasło ustawione przy rejestracji. Do celów deweloperskich klucz API można także przekleić ręcznie z profilu użytkownika.
Parametry:
adres mailowy użytkownika podany przy rejestracji. Parametr obowiązkowy. | |
password | hasło użytkownika. Parametr obowiązkowy. |
Odpowiedź po pomyślnym zalogowaniu: 200
api_key | klucz API |
---|
Odpowiedź gdy email lub hasło są nieprawidłowe: 401
Portfele i rachunki bankowe
API daje możliwość wylistowania wszystkich rachunków bankowych i portfeli z ich saldami. Portfele są traktowane analogicznie jak rachunki. Saldo portfela aktualizuje się automatycznie na serwerze, gdy do portfela wpadają nowe wydatki lub przychody. Salda rachunków bankowych również aktualizują się automatycznie na serwerze podczas importu danych przez użytkownika.
Parametry: brak
Odpowiedź:
id | identyfikator obiektu |
---|---|
currency-balance | saldo rachunku bankowego w walucie. Powinno być wyświetlane razem z nazwą waluty. |
currency-name | trzyliterowa nazwa waluty, np. "EUR" |
balance | saldo przeliczone na PLN. Służy jako wspólny mianownik (PLN) przy sumowaniu sald. Generalnie ta kwota nie powinna być wyświetlana, chyba że jako dodatkowa informacja o złotówkowej wartości salda walutowego currency-balance. |
iban-checksum | suma kontrolna oryginalnego IBAN-u |
iban | skrót kryptograficzny IBAN-u |
display-name | nazwa rachunku lub portfela, którą powinieneś wyświetlać; jest to najlepsza z nazw jaką dysponuje Kontomierz (szczegóły: nazwa użytkownika nadana w Kontomierzu ma priorytet nad nazwą użytkownika nadaną w systemie bankowym, która znów ma priorytet nad oficjalną nazwą rachunku) |
bank-name | nazwa banku, którą możesz wyświetlać, ale nie możesz hardkodować w kodzie (jest zmienna) |
bank-plugin-name | niezmienny symbol banku, który możesz hardkodować w kodzie; dla pseudobanku zawierającego portfele przyjmuje wartość "Wallets"; używaj tego do rozróżnienia portfeli od kont bankowych |
is-default-wallet | true jeśli jest to portfel domyślny; false w przeciwnym wypadku; wartość ma sens tylko dla portfeli i pozwala ustalić, który portfel użytkownik wybrał jako domyślny (główny) |
apy | oprocentowanie, matematycznie (np. 0.02 to 2%) |
Dodaje nowy portfel gotówkowy.
Parametry:
user_account[user_name] | nazwa portfela nadawana przez użytkownika. Jeśli zostanie pusta, portfel będzie figurował pod domyślną nazwą skonfigurowaną po stronie serwera. |
---|---|
user_account[currency_balance] | saldo portfela. Parametr obowiązkowy. |
user_account[currency_name] | trzyliterowa nazwa waluty, np. "GBP". Parametr obowiązkowy. |
user_account[liquid] | określa czy saldo portfela ma być traktowane jako środki bieżące ('1') czy jako oszczędności ('0'). Domyślnie '1'. |
Odpowiedź po pomyślnym utworzeniu portfela: 201
Odpowiedź po błędzie: 422
errors | słownik błędów na poszczególnych polach, np. { "errors": { "currency_amount": ["- musi być liczbą"] } } |
---|
Aktualizuje portfel gotówkowy o identyfikatorze :id.
Parametry: jak przy tworzeniu portfela
Odpowiedź po pomyślnej aktualizacji portfela: 200
Odpowiedź po błędzie: 422, treść odpowiedzi jak przy dodawaniu portfela
Usuwa portfel o identyfikatorze id. Usunięcie portfela uda się tylko jeśli nie jest to portfel główny oraz nie są do niego przypisane rachunki bankowe. W przeciwnym wypadku serwer zwróci 422. Wybór portfela głównego oraz przypisania rachunków do portfeli obecnie dostępne są tylko z poziomu aplikacji webowej.
Parametry: brak
Odpowiedź po pomyślnym usunięciu: 200
Odpowiedź w przypadku odmowy: 422
Transakcje
Lista transakcji użytkownika, stronicowana i przefiltrowana według zadanych kryteriów.
Parametry:
page | strona wyników. Dozwolone wartości od 1 w górę. Domyślnie 1. |
---|---|
per_page | liczba transakcji na stronie. Dozwolone wartości od 1 do 100. Domyślnie wartość ustawiona przez użytkownika w Kontomierzu. |
user_account_id | identyfikator rachunku bankowego użytkownika |
q | szukany tekst |
start_on | data od w formacie DD-MM-RRRR. Domyślnie pierwszy dzień bieżącego miesiąca. |
end_on | data do w formacie DD-MM-RRRR. Domyślnie ostatni dzień bieżącego miesiąca. |
direction | "kierunek" transakcji. Dozwolone są 3 wartości: all, withdrawals, deposits. Domyślnie all. W GUI stosujemy tu słownictwo: wszystkie, wydatki, przychody. |
tag_name | tag (etykieta) transakcji. Parametr umożliwia filtrowanie transakcji po tagu. Listę tagów użytych kiedykolwiek przez użytkownika (a zatem listę sensownych wartości tego pola) można uzyskać pod /k4/tags.:format |
category_group_id | identyfikator grupy kategorii |
category_id | identyfikator kategorii |
show_hidden_transactions | uwzględnij również nieistotne transackje. Dozwolone są 2 wartości: true, false. |
order_by | TODO (nie zaimplementowane) |
Odpowiedź: jak w szczegółach transakcji poniżej
Szczegóły transakcji o identyfikatorze id.
Parametry: brak
Odpowiedź:
id | identyfikator obiektu |
---|---|
user-account-id | identyfikator rachunku bankowego |
currency-amount | kwota transakcji w swojej oryginalnej walucie. Powinna być wyświetlana łącznie z nazwą waluty. |
currency-name | trzyliterowa nazwa waluty, np. "PLN" |
amount | kwota transakcji przeliczona na PLN. Służy jako wspólny mianownik (PLN) przy sumowaniu transakcji. Generalnie nie powinna być wyświetlana, chyba że jako dodatkowa informacja o złotówkowej wartości kwoty walutowej currency-amount. |
transaction-on | data transakcji wyświetlana w Kontomierzu |
booked-on | data księgowania, mniej istotna z punktu widzenia użytkownika. Może być wyświetlana w szczegółach transakcji. |
description | opis transakcji. Opis jest budowany "inteligentnie" przez Kontomierz na bazie 1) opisu użytkownika (jeśli znany) 2) strony transakcji (jeśli znana) 3) tytułu transakcji (jeśli znany) 4) rodzaju transakcji |
category-name | nazwa kategorii |
category-id | identyfikator kategorii |
tag-string | tagi (etykiety) transakcji oddzielone przecinkiem |
Utworzenie transakcji w portfelu. Użyj tego, aby dodawać do portfela wydatki i przychody gotówkowe. Obecnie nie ma możliwości tworzenia transakcji na zwykłych kontach bankowych.
Parametry:
money_transaction[user_account_id] | identyfikator portfela. Domyślnie transakcja trafi do portfela domyślnego. |
---|---|
money_transaction[category_id] | identyfikator kategorii. Domyślnie transakcja otrzyma kategorię swojej poprzedniczki. |
money_transaction[currency_amount] | dodatnia kwota w oryginalnej walucie. Czy jest to wydatek czy przychód ustala się za pomocą parametru "direction". Pozwala to łatwiej zbudować formularz dla użytkownika, w którym najpierw wybiera czy chce dodać wydatek czy przychód, a następnie zawsze wprowadza dodatnią kwotę. Domyślnie transakcja otrzyma kwotę swojej poprzedniczki w portfelu. |
money_transaction[currency_name] | trzyliterowa nazwa waluty, np. "GBP". Domyślnie transakcja otrzyma walutę portfela. |
money_transaction[direction] | kierunek kwoty. Określa czy jest to wydatek czy przychód. Dozwolone wartości to "withdrawal" (wydatek) i "deposit" (przychód). Domyślnie "withdrawal". |
money_transaction[tag_string] | lista tagów oddzielonych przecinkiem |
money_transaction[name] | opis transakcji. Domyślnie transakcja otrzyma opis swojej poprzedniczki. |
money_transaction[transaction_on] | data transakcji w formacie DD-MM-RRRR. Domyślnie bieżący dzień. |
money_transaction[client_assigned_id] | zewnętrzny, unikalny identyfikator transakcji generowany przez klienta API. W praktyce najłatwiej go uzyskać na podstawie znacznika czasowego. Przykład: "1665050371". Kontomierz wykorzystuje ten identyfikator aby uniknąć namnażania tej samej transakcji w przypadku, gdy klient wielokrotnie próbuje ją wysłać, np. na skutek problemów z siecią. Parametr obowiązkowy. |
Odpowiedź:
parametry poprawne? | szczegóły dodanej transakcji (identycznie jak przy bezpośrednim zapytaniu o szczegóły transakcji). Klient API uzyskuje w ten sposób bazodanowy identyfikator transakcji (id) nadany przez Kontomierz. |
---|---|
parametry błędne? | lista błędów na poszczególnych polach |
Aktualizacja transakcji w portfelu lub na koncie bankowym.
Parametry: jak przy dodawaniu wydatku, oprócz money_transaction[client_assigned_id], którego tu się już nie wysyła.
Odpowiedź: jak przy dodawaniu wydatku.
Usunięcie transakcji o identyfikatorze id z portfela lub rachunku bankowego.
Parametry: brak
Odpowiedź: 200
Kategorie
Drzewo kategorii. Będzie Ci potrzebne w formularzu transakcji.
Parametry:
direction | Dozwolone wartości to "withdrawal" (drzewo kategorii wydatkowych) i "deposit" (drzewo kategorii przychodowych). Uwaga: nie możesz pozwolić użytkownikowi na przypisanie kategorii przychodowej do wydatku i vice versa. Parametr obowiązkowy. |
---|---|
in_wallet | Dozwolone wartości: "true". W przyszłości wartość "false" pozwoli odzyskać drzewo kategorii dla transakcji pozaportfelowych. Parametr obowiązkowy. |
Tagi
Tagi użytkownika posortowane od ostatnio do najwcześniej używanych. Będą Ci potrzebne w formularzu transakcji jako opcjonalna podpowiedź dla pola listy tagów (tag_string).
Parametry: brak
Odpowiedź:
id | identyfikator obiektu |
---|---|
name | nazwa taga |
Budżety
Lista budżetów na określony miesiąc.
Parametry:
month_on | Miesiąc budżetowy. Format: 01-MM-RRRR. Przykład: 01-05-2011. Domyślnie bieżący miesiąc. |
---|
Odpowiedź:
id | identyfikator obiektu |
---|---|
limit | wysokość budżetu |
amount | kwota już wydana |
kind |
Budżet "total" to całkowity budżet miesięczny definiowany przez użytkownika. Budżet "ordinary" to zwykły budżet miesięczny założony przez użytkownika na kategorię lub grupę kategorii wydatków. Budżet "other" obejmuje pozostałe kategorie i jest obliczany przez Kontomierz jako różnica pomiędzy budżetem całkowitym i zdefiniowanymi podbudżetami. Budżetu "other" nie można zatem edytować. |
name |
przyjazna nazwa budżetu do wyświetlenia w UI |
category-id |
identyfikator kategorii odpowiadającej temu budżetowi (obecny tylko dla budżetów na kategorie i dla budżetu "other"). Dla budżetu "other" będzie to lista identyfikatorów kategorii. Format listy nadaje się do bezpośredniego użycia jako parametr w żądaniu o transakcje. |
category-group-id |
identyfikator grupy kategorii odpowiadającej temu budżetowi (obecny tylko dla budżetów na grupy kategorii). |
Dodaje nowy budżet. Użyj tego, aby zdefiniować budżet w wybranym miesiącu na określoną grupę lub kategorię wydatków. W parametrach należy podać albo id kategorii albo id grupy (nie oba jednocześnie). Wywołanie może zakończyć się błędem (422) m.in. gdy podano nieprawidłową kwotę lub budżet na daną grupę/kategorię w danym miesiącu już istnieje.
Parametry:
budget[limit] | kwota budżetu. Parametr obowiązkowy. |
---|---|
budget[category_id] | identyfikator kategorii |
budget[category_group_id] | identyfikator grupy kategorii |
budget[month_on] | miesiąc dla którego definiowany jest budżet. Domyślnie bieżący. |
Odpowiedź po pomyślnym utworzeniu budżetu: 201
Odpowiedź po błędzie: 422
errors | słownik błędów na poszczególnych polach, np. { "errors": { "limit": ["- musi być liczbą"] } } |
---|
Aktualizuje budżet o identyfikatorze :id.
Parametry:
budget[limit] | kwota budżetu. Parametr obowiązkowy. |
---|
Odpowiedź po pomyślnej aktualizacji budżetu: 200
Odpowiedź po błędzie: jak przy tworzeniu budżetu
Usunięcie budżetu o identyfikatorze id.
Parametry: brak
Odpowiedź po pomyślnym usunięciu: 200
Skopiuje do bieżącego miesiąca wszystkie budżety z ostatniego miesiąca. Jeśli w ostatnim miesiącu brakuje budżetów, zostanie wzięty wcześniejszy, aż do skutku. Jeśli w bieżącym miesiącu istnieją już jakieś budżety, to nie zostaną nadpisane.
Parametry: brak
Odpowiedź: 201
Płatności (planer finansowy)
Planer płatności umożliwia definiowanie cyklicznych wydatków i przychodów. Z punktu widzenia obiektów biznesowych rozróżniamy harmonogram (schedule) oraz pojedynczą płatność (scheduled_transaction).
Harmonogramy możemy tworzyć, edytować i usuwać. Płatności możemy oznaczać jako zapłacone/niezapłacone.
Płatności są wystąpieniami harmonogramu obliczanymi dynamicznie na serwerze. Dlatego nie ma np. możliwości edycji pojedynczej płatności. Edytować można tylko cały harmonogram.
Lista płatności spełniających zadane kryteria.
Parametry:
page | strona wyników. Dozwolone wartości od 1 w górę. Domyślnie 1. |
---|---|
per_page | liczba transakcji na stronie. Dozwolone wartości od 1 do 100. Domyślnie wartość ustawiona przez użytkownika w Kontomierzu. |
start_on | data od w formacie DD-MM-RRRR. Domyślnie pierwszy dzień bieżącego miesiąca. |
end_on | data do w formacie DD-MM-RRRR. Domyślnie ostatni dzień bieżącego miesiąca. |
direction | "kierunek" transakcji. Dozwolone są 3 wartości: all, withdrawals, deposits. Domyślnie all. W GUI stosujemy tu słownictwo: wszystkie, wydatki, przychody. |
schedule_group_name |
filtr rodzaju płatności.
Parametr obowiązkowy.
Możliwe wartości to
|
Odpowiedź: 200, atrybuty poszczególnych płatności:
schedule-id | identyfikator harmonogramu do którego należy ta płatność |
---|---|
transaction-on | data wystąpienia płatności |
description | opis płatności |
currency-amount | kwota transakcji w swojej oryginalnej walucie. Powinna być wyświetlana łącznie z nazwą waluty. |
currency-name | trzyliterowa nazwa waluty, np. "PLN" |
paid | true|false w zależności czy płatność jest zrealizowana czy nie |
Szczegóły harmonogramu.
Odpowiedź: 200, atrybuty harmonogramu:
id | identyfikator harmonogramu |
---|---|
next-deadline-on | data najbliższej płatności (może być w przeszłości jeśli płatność jest spóźniona) |
description | opis harmonogramu |
currency-amount | kwota płatności w swojej oryginalnej walucie. Powinna być wyświetlana łącznie z nazwą waluty. |
currency-name | trzyliterowa nazwa waluty, np. "PLN" |
repeat | cykliczność (opis w dokumentacji tworzenia harmonogramu) |
repeat-description | opis cykliczności nadajcy się do wyświetlenia użytkownikowi |
holidays | zachowanie gdy płatność wypadnie w weekend |
holidays-description | opis zachowania gdy płatność wypadnie w weekend nadajcy się do wyświetlenia użytkownikowi |
Dodaje nowy harmonogram płatności.
Parametry:
schedule[direction] | withdrawal | deposit Parametr obowiązkowy. |
---|---|
schedule[deadline_on] | najbliższy termin płatności w formacie DD-MM-RRRR. Parametr obowiązkowy. |
schedule[holidays] |
jeśli wypadnie w święto:
|
schedule[description] | opis harmonogramu (nazwa płatności) Parametr obowiązkowy. |
schedule[currency_amount] | kwota Parametr obowiązkowy. |
schedule[currency_name] | trzyliterowy skrót waluty, obecnie obowiązkowo PLN Parametr obowiązkowy. |
schedule[repeat] |
powtarzalność:
|
Odpowiedź po pomyślnym utworzeniu harmonogramu: 201
Odpowiedź po błędzie: 422
errors | słownik błędów na poszczególnych polach |
---|
Aktualizuje harmonogram płatności.
Parametry: jak przy dodawaniu harmonogramu.
Odpowiedź po pomyślnej aktualizacji harmonogramu: 200
Odpowiedź po błędzie: 422
errors | słownik błędów na poszczególnych polach |
---|
Oznaczenie płatności przypadającej na :date w harmonogramie :id jako zrealizowanej (zapłaconej). Fragment URL-a ":date" powinien być w formacie DD-MM-RRRR, np. "20-01-2013".
Parametry: brak
Odpowiedź w pomyślnym przypadku: 200
Oznaczenie płatności przypadającej na :date w harmonogramie :id jako niezrealizowanej (niezapłaconej). Fragment URL-a ":date" powinien być w formacie DD-MM-RRRR, np. "20-01-2013".
Można w ten sposób anulować niechciane oznaczenie płatności zrealizowanej.
Parametry: brak
Odpowiedź w pomyślnym przypadku: 200
Usunięcie harmonogramu o identyfikatorze id.
Parametry: brak
Odpowiedź po pomyślnym usunięciu: 200
Historia majątku
Lista punktów w historii majątku (tzw. wealth points). Każdy punkt reprezentuje całkowity stan posiadania użytkownika na koniec danego miesiąca. Aby odzyskać historię majątku z danego okresu, należy podać parametry start_on i end_on.
Parametry:
start_on | data od w formacie DD-MM-RRRR. Domyślnie pierwszy dzień bieżącego miesiąca. |
---|---|
end_on | data do w formacie DD-MM-RRRR. Domyślnie ostatni dzień bieżącego miesiąca. |
Odpowiedź:
id | identyfikator obiektu |
---|---|
date-on | data, na którą przypada punkt |
amount | kwota reprezentująca całkowity stan posiadania (majątek) |
notes | opcjonalny opis miesiąca nadawany przez użytkownika |
Wykresy kołowe
Zwraca dane potrzebne do wyświetlenia wykresu kołowego.
Wykresy kołowe obrazują rozbicie wydatków/przychodów na kategorie w wybranym okresie (np. bieżącym miesiącu).
Podobnie jak lista transakcji, wykresy mogą być zawężone do transakcji spełniających wybrane kryteria. Możesz np. uzyskać wykres dla transakcji z ubiegłego kwartału, z grupy Zakupy, jednocześnie posiadających tag "ważne".
Dostępne są 4 wykresy kołowe:
- stosunek wydatków do przychodów
- rozbicie wydatków na grupy kategorii (Zakupy, Rachunki, Zdrowie, ...)
- rozbicie wydatków na kategorie w ramach wybranej grupy (np. dla wybranej grupy Zakupy rozbicie na kategorie Spożywcze, Chemia, Elektronika, ...)
- rozbicie przychodów na kategorie
Kontomierz zawsze zwraca wykres relewantny do kryteriów wyszukiwania.
Jak tego używać? - Pomyśl, które transakcje chcesz zobrazować na wykresie. Dobierz kryteria wyszukiwania. Następnie wyświetl zwrócony wykres. Przykłady:
- jeśli nie podasz żadnych kryteriów - wykres 1
- jeśli wybierzesz tylko wydatki (direction='withdrawals') - wykres 2
- jeśli wybierzesz tylko przychody (direction='deposits') - wykres 4
- jeśli wybierzesz grupę kategorii Zakupy (category_group_id=...) - wykres 3
- jeśli wybierzesz grupę kategorii Przychody (category_group_id=...) - wykres 4
Parametry: jak przy wyszukiwarce transakcji, plus:
chart_kind | Dozwolone wartości to "pie". Parametr obowiązkowy. (W przyszłości dostępne będą inne rodzaje wykresów). |
---|
Odpowiedź:
data |
dane dla poszczególnych fragmentów (trójkątów) wykresu kołowego, gdzie:
|
---|---|
type |
typ wykresu, możliwe 4 wartości:
|
Waluty
Słownik walut z podziałem na główne (major), drugorzędne (minor) i trzeciorzędne (trivial).
Parametry: brak
Odpowiedź:
id | identyfikator obiektu. Wysyłaj go tam gdzie potrzeba currency_id. |
---|---|
name | nazwa waluty. Wysyłaj ją tam gdzie potrzeba currency_name. |
importance | istotność waluty [major, minor, trivial. Pozwala zorganizować słownik walut w sposób przyjazny użytkownikowi. |
full-name | pełna nazwa waluty. Opcjonalnie może być prezentowana w UI. |
Przykłady
Poniżej zamieszczamy kilka przykładowych żądań API dla użytkownika DEMO.
Rachunki bankowe i portfel:
https://secure.kontomierz.pl/k4/user_accounts.xml?api_key=e7cOI9zZTbprBddSHHnlniLsAvzBpfhqTIjeUid2be0fjb2REaWnudZqGSgxz1Lz
Wszystkie transakcje (strona 1):
https://secure.kontomierz.pl/k4/money_transactions.xml?start_on=01-01-2000&api_key=e7cOI9zZTbprBddSHHnlniLsAvzBpfhqTIjeUid2be0fjb2REaWnudZqGSgxz1Lz
Wszystkie transakcje (strona 2):
https://secure.kontomierz.pl/k4/money_transactions.xml?start_on=01-01-2000&page=2&api_key=e7cOI9zZTbprBddSHHnlniLsAvzBpfhqTIjeUid2be0fjb2REaWnudZqGSgxz1Lz
Transakcje zawierające w opisie "a" (strona 1):
https://secure.kontomierz.pl/k4/money_transactions.xml?start_on=01-01-2000&q=a&api_key=e7cOI9zZTbprBddSHHnlniLsAvzBpfhqTIjeUid2be0fjb2REaWnudZqGSgxz1Lz
Drzewo kategorii dla wydatku gotówkowego:
https://secure.kontomierz.pl/k4/categories.xml?direction=withdrawal&in_wallet=true&api_key=e7cOI9zZTbprBddSHHnlniLsAvzBpfhqTIjeUid2be0fjb2REaWnudZqGSgxz1Lz
Drzewo kategorii dla przychodu gotówkowego:
https://secure.kontomierz.pl/k4/categories.xml?direction=deposit&in_wallet=true&api_key=e7cOI9zZTbprBddSHHnlniLsAvzBpfhqTIjeUid2be0fjb2REaWnudZqGSgxz1Lz
Tagi użytkownika:
https://secure.kontomierz.pl/k4/tags.xml?api_key=e7cOI9zZTbprBddSHHnlniLsAvzBpfhqTIjeUid2be0fjb2REaWnudZqGSgxz1Lz
Budżety w ubiegłym miesiącu:
https://secure.kontomierz.pl/k4/budgets.xml?month_on=01-12-2020&api_key=e7cOI9zZTbprBddSHHnlniLsAvzBpfhqTIjeUid2be0fjb2REaWnudZqGSgxz1Lz
Płatności zaplanowane:
https://secure.kontomierz.pl/k4/scheduled_transactions.xml?schedule_group_name=unpaid&start_on=01-01-2009&api_key=e7cOI9zZTbprBddSHHnlniLsAvzBpfhqTIjeUid2be0fjb2REaWnudZqGSgxz1Lz
Płatności zrealizowane:
https://secure.kontomierz.pl/k4/scheduled_transactions.xml?schedule_group_name=paid&start_on=01-01-2009&api_key=e7cOI9zZTbprBddSHHnlniLsAvzBpfhqTIjeUid2be0fjb2REaWnudZqGSgxz1Lz
Wykres kołowy - stosunek wydatków do przychodów:
https://secure.kontomierz.pl/k4/charts/money_transactions.xml?start_on=01-01-2000&chart_kind=pie&api_key=e7cOI9zZTbprBddSHHnlniLsAvzBpfhqTIjeUid2be0fjb2REaWnudZqGSgxz1Lz
Wykres kołowy - rozbicie wydatków na grupy kategorii:
https://secure.kontomierz.pl/k4/charts/money_transactions.xml?start_on=01-01-2000&direction=withdrawals&chart_kind=pie&api_key=e7cOI9zZTbprBddSHHnlniLsAvzBpfhqTIjeUid2be0fjb2REaWnudZqGSgxz1Lz
Wykres kołowy - rozbicie przychodów na grupy kategorii:
https://secure.kontomierz.pl/k4/charts/money_transactions.xml?start_on=01-01-2000&direction=deposits&chart_kind=pie&api_key=e7cOI9zZTbprBddSHHnlniLsAvzBpfhqTIjeUid2be0fjb2REaWnudZqGSgxz1Lz
Wskazówki implementacyjne
Bezpieczeństwo
Wszystkie żądania API są po HTTPS. Znajdź taką bibliotekę HTTP dla Twojego języka, która w pełni obsługuje ten protokół. Upewnij się, że Twoja biblioteka/platforma prawidłowo weryfikuje certyfikaty SSL.
Nie zapisuj e-maila i hasła użytkownika w pamięci trwałej.
Klucz API zapisuj w sposób uniemożliwiający/utrudniający wykradzenie go przez inne aplikacje (w zależności od możliwości Twojej platformy).
Synchronizacja client «-» server
Założenia
- Aplikacja mobilna musi być przygotowana na czasową niedostępność sieci i losowe niedochodzenie żądań do serwera. Rozumiemy przez to prawidłową obsługę błędów i stosowne komunikaty dla użytkownika. Najczęściej sama platforma mobilna dostarcza taki mechanizm.
-
Aplikacja mobilna musi keszować dane pobierane z serwera.
- Aby nie wykonywać powolnych żądań za każdym razem przy zmianie ekranu.
- Aby dało się przeglądać ostatnio znany stan offline.
- Użytkownik nie będzie korzystał w tym samym momencie z wersji webowej i mobilnej. Przyjmujemy te założenie aby uprościć reguły synchronizacji danych.
Synchronizacja serwer -» klient ("pull")
-
dane możemy podzielić na:
-
niekeszowalne
- email i hasło do Kontomierza (zakaz zapisywania w telefonie)
- wyszukiwarka bankomatów
-
keszowalne często-zmienne ("finansowe")
- lista portfeli i rachunków
- lista transakcji na określonym portfelu/rachunku
- lista budżetów
- listy płatności
- dane do wykresów
-
keszowalne rzadko-zmienne ("słownikowe")
- drzewo kategorii wydatkowych dla portfeli
- drzewo kategorii przychodowych dla portfeli
- lista tagów
- lista walut
-
keszowalne na stałe
- klucz API
-
niekeszowalne
-
kiedy inwalidować cache danych rzadko-zmiennych ("słownikowych")?
- po zalogowaniu
- na żądanie użytkownika (Ustawienia / Odśwież dane)
-
kiedy inwalidować cache danych często-zmiennych ("finansowych")?
- po zalogowaniu
- po każdej udanej modyfikacji dowolnego obiektu (nowy lub edycja) -> cały cache danych często-zmiennych musi być inwalidowany
- po powrocie do aplikacji rozumianym jako dłuższa przerwa w korzystaniu
- na żądanie użytkownika (Ustawienia / Odśwież dane)
-
co rozumiemy przez "inwalidację"?
- oznaczenie danych jako nieświeże (NIE usunięcie!)
- dane nieświeże powinny być prezentowane do czasu ściągnięcia z serwera aktualnych
-
użytkownik wchodzi w ekran z nieświeżymi (inwalidowanymi) danymi; co ma zrobić aplikacja?
- pokazać nieświeże dane
- pokazać ikonkę symbolizującą synchronizację (łączenie się z serwerem)
- zażądać z serwera świeżych danych dla tego ekranu
- zastąpić dane nieświeże otrzymanymi (TODO: co w przypadku niepowodzenia?)
-
czy użytkownik może edytować nieświeży obiekt? Co ma wtedy zrobić aplikacja?
- "nieświeżość" to tylko heurystyka %li obiekt zawsze może okazać się zmodyfikowany lub nawet usunięty z serwera
- dlatego aplikacja musi zawsze spodziewać się, że serwer zwróci błąd przy zapisie obiektu
- nie ma zatem motywacji do blokowania edycji obiektów podejrzewanych o nieświeżość
Synchronizacja klient -» serwer ("push")
Zasadniczo edycja danych powinna być możliwa tylko w trybie online (aktywne połączenie z siecią). Przy "zapisz" obiekt powinien być natychmiast wysyłany do Kontomierza zgodnie z API. Jeśli żądanie się nie powiedzie (problemy z siecią), aplikacja nie powinna sama ponawiać żądania. W ten sposób unikamy problemów z synchronizacją.
Wyjątkiem od tej reguły jest dodawanie i edycja transakcji w portfelach (wydatków i przychodów gotówkowych). Ta operacja jest tak częsta, że chcemy aby była możliwa również offline.
Ściślej, offline możliwe powinno być:
- dodanie transakcji do portfela
- edycja niewysłanej transakcji w portfelu
- usunięcie niewysłanej transakcji z portfela
Transakcja wprowadzona offline powinna być wysyłana aż do uzyskania poprawnej odpowiedzi z serwera. Poprawna odpowiedź z serwera gwarantuje, że wydatek został zapisany. Należy wtedy usunąć lokalną transakcję i pobrać świeżą listę transakcji z Kontomierza, gdzie będzie ona już figurowała.
Przed wielokrotnym dodaniem tej samej transakcji do bazy chroni jej atrybut client_assigned_id. Serwer gwarantuje, że dwie transakcje o tym samym client_assigned_id nie zostaną zapisane.
Pochwal się!
Chętnie odpowiemy na Twoje pytania. Chcemy usłyszeć o Twojej aplikacji. Chcemy ją promować. Poinformuj nas o swoich dokonaniach! Napisz: [email protected]