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

POST /k4/users:format

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?

POST /k4/session.:format

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:

email 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

GET /k4/user_accounts.:format

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%)

POST k4/user_accounts/create_wallet.:format

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ą"] } }
PUT /k4/user_accounts/:id/update_wallet.:format

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

DELETE /k4/user_accounts/:id/destroy_wallet.:format

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

GET /k4/money_transactions.:format

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

GET /k4/money_transactions/:id.:format

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
POST /k4/money_transactions.:format

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
PUT /k4/money_transactions/:id.:format

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.

DELETE /k4/money_transactions/:id.:format

Usunięcie transakcji o identyfikatorze id z portfela lub rachunku bankowego.

Parametry: brak

Odpowiedź: 200

Kategorie

GET /k4/categories.:format

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

GET /k4/tags.:format

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

GET /k4/budgets.:format

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).

POST /k4/budgets.:format

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ą"] } }
PUT /k4/budgets/:id.:format

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

DELETE /k4/budgets/:id.:format

Usunięcie budżetu o identyfikatorze id.

Parametry: brak

Odpowiedź po pomyślnym usunięciu: 200

POST /k4/budgets/copy_from_last_to_present_month.:format

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.

GET /k4/scheduled_transactions.:format

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
  • unpaid - zaplanowane wydatki i przychody
  • paid - zrealizowane wydatki i przychody

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
GET /k4/schedules/:id:format

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
POST /k4/schedules.:format

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:
  • 0 - nie przesuwaj
  • 1 - przesuń na ost. dzień roboczy przed weekendem
  • 2 - przesuń na pierwszy d. roboczy po weekendzie
Parametr obowiązkowy.
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ść:
  • 1 - tylko raz
  • 8 - co tydzień
  • 9 - co dwa tygodnie
  • 2 - co miesiąc
  • 7 - co dwa miesiące
  • 3 - co kwartał
  • 4 - co pół roku
  • 5 - co roku
  • 6 - co dwa lata
Parametr obowiązkowy.

Odpowiedź po pomyślnym utworzeniu harmonogramu: 201

Odpowiedź po błędzie: 422

errors słownik błędów na poszczególnych polach
PUT /k4/schedules/:id.:format

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
PUT /k4/schedules/:id/mark_as_payed/:date.:format

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

PUT /k4/schedules/:id/mark_as_unpayed/:date.:format

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

DELETE /k4/schedules/:id.:format

Usunięcie harmonogramu o identyfikatorze id.

Parametry: brak

Odpowiedź po pomyślnym usunięciu: 200

Historia majątku

GET /k4/wealth_points.:format

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

GET /k4/charts/money_transactions.:format

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:

  1. stosunek wydatków do przychodów
  2. rozbicie wydatków na grupy kategorii (Zakupy, Rachunki, Zdrowie, ...)
  3. rozbicie wydatków na kategorie w ramach wybranej grupy (np. dla wybranej grupy Zakupy rozbicie na kategorie Spożywcze, Chemia, Elektronika, ...)
  4. 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:

  1. jeśli nie podasz żadnych kryteriów - wykres 1
  2. jeśli wybierzesz tylko wydatki (direction='withdrawals') - wykres 2
  3. jeśli wybierzesz tylko przychody (direction='deposits') - wykres 4
  4. jeśli wybierzesz grupę kategorii Zakupy (category_group_id=...) - wykres 3
  5. 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:
  • name - nazwa (użyj jako fragment etykiety)
  • y - kwota, zawsze w PLN
  • color - kolor na stałe przypisany do danej grupy kategorii / kategorii. Jest istotne żeby był spójny za aplikacją webową.
  • z - istotne tylko, jeśli chcesz uczynić swój wykres interaktywnym. Jest to kryterium wyszukiwania, które powinieneś dodać gdy użytkownik wybierze ten fragment wykresu; np. identyfikator kategorii (category_id), identyfikator grupy kategorii (category_group_id), nazwa kierunku (direction)
type typ wykresu, możliwe 4 wartości:
  1. incomes-vs-spendings (wykres 1.)
  2. spendings-in-category-groups (wykres 2.)
  3. spendings-in-categories (wykres 3.)
  4. incomes-in-categories (wykres 4.)

Waluty

GET /k4/currencies.:format

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

Waluty:
https://secure.kontomierz.pl/k4/currencies.xml?api_key=e7cOI9zZTbprBddSHHnlniLsAvzBpfhqTIjeUid2be0fjb2REaWnudZqGSgxz1Lz

Budżety w ubiegłym miesiącu:
https://secure.kontomierz.pl/k4/budgets.xml?month_on=01-05-2021&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
  • 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?
    1. pokazać nieświeże dane
    2. pokazać ikonkę symbolizującą synchronizację (łączenie się z serwerem)
    3. zażądać z serwera świeżych danych dla tego ekranu
    4. 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: kontakt@kontomierz.pl

Nowe zasady dotyczące cookies. Używamy plików cookies do zapewnienia Ci wygodnego korzystania z serwisu, gromadzenia danych analitycznych i statystycznych oraz wyświetlania reklam dostosowanych do Twoich preferencji i przeglądanych treści. Kontynuując przeglądanie zgadzasz się na wykorzystanie plików cookies w powyższym celu przez nas (Kontomierz.pl sp. z o.o.) i naszych partnerów. Możesz zmienić warunki przechowywania i dostępu do plików cookies, w tym zablokować te pliki, w ustawieniach przeglądarki. W związku z korzystaniem z serwisu przetwarzamy również dane osobowe. Zapoznaj się z polityką prywatności Kontomierz.pl, aby dowiedzieć się więcej o przetwarzaniu Twoich danych osobowych i plikach cookies.