Kontomierz API
Wstęp
Oddajemy w Twoje ręce proste i nowoczesne API abyś mógł używać części Kontomierza na swoich warunkach. W oparciu o to API powstały już dwie dojrzałe aplikacje - na iPhone'a i na Androida. Zachęcamy do zabawy!
Możliwości API
- dodawanie, modyfikacja i usuwanie wydatków i przychodów z portfeli
- lista kont bankowych i portfeli wraz z saldami (stan finansów)
- lista transakcji w ramach wybranego konta bankowego lub portfela
- wyszukiwarka transakcji (wiele kryteriów)
Zarys techniczny:
- HTTP REST API
- Wyniki w JSON lub XML (do wyboru - obie wersje działają równolegle)
- Bezsesyjne
Uwierzytelnienie
API jest bezsesyjne, czyli klient HTTP nie powinien wysyłać żadnych ciastek.
Każde żądanie uwierzytelniane jest niezależnie metodą HTTP Basic Auth.
W przeglądarkach internetowych i dobrych bibliotekach-klientach HTTP sprowadza się to do dopisania "login:password@" do adresu URL, np.:
| login | demo%40kontomierz.pl ("%40" to enkodowane "@") |
|---|---|
| hasło | demo123 |
| żądanie | https://demo%40kontomierz.pl:demo123@kontomierz.pl/user_accounts.xml |
W innych bibliotekach jak np. Apache HTTP, istnieją klasy i metody pozwalające ustawić login i hasło na obiekcie żądania, co fizycznie sprowadza się ustawienia nagłówków HTTP.
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 |
Konta bankowe i portfele
API daje możliwość wylistowania wszystkich kont bankowych i portfeli z ich saldami. Portfele są traktowane analogicznie jak konta. Saldo portfela aktualizuje się automatycznie na serwerze, gdy do portfela wpadają nowe wydatki lub przychody. Salda kont bankowych również aktualizują się automatycznie na serwerze podczas importu danych przez użytkownika.
Parametry: brak
Odpowiedź:
| id | identyfikator obiektu |
|---|---|
| balance | saldo w PLN |
| currency-balance | saldo w natywnej walucie |
| iban | skrót kryptograficzny IBAN-u |
| iban-checksum | suma kontrolna oryginalnego IBAN-u |
| best-name | nazwa konta 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ą konta) |
| 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 rozpoznania portfeli do kont bankowych |
| account-name | oficjalna nazwa konta bankowego, którą ewentualnie możesz wyświetlać jako drugorzędną w stosunku do best-name; dla portfeli przyjumuje wartość "Pieniądze w portfelu", ale nie można tego hardkodować (zmienia się) |
| 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) |
| currency-name | trzyliterowa nazwa waluty, np. "PLN" |
| apy | oprocentowanie, matematycznie (np. 0.02 to 2%) |
Uwaga: nie można polegać na pozostałych zwracanych wartościach. Zostaną one wkrótce usunięte z API. Prosimy bazować wyłącznie na wartościach udokumentowanych powyżej.
Transakcje
Stronicowana lista wszystkich transakcji użytkownika.
Parametry:
| page | strona wyników |
|---|---|
| user_account_id | identyfikator konta |
| q | szukany tekst |
| start_on | data od w formacie RRRR-MM-DD |
| end_on | data do w formacie RRRR-MM-DD |
| direction | "kierunek" transakcji, jedno z: all | withdrawals | deposits |
| category_group_id | identyfikator grupy kategorii |
| category_id | identyfikator kategorii |
| without_categories | lista identyfikatorów kategorii do pominięcia oddzielona minusem, np. 25-30-31 |
| order_by | kolumna po której mają być sortowane transakcje. Biała lista możliwych wartości: {id created_at updated_at amount balance transaction_on booked_on categories.name}. Do każdej można dopisać " asc" lub " desc" aby określić kierunek. |
Odpowiedź: jak w szczegółach transakcji poniżej
Stronicowana lista wszystkich transakcji użytkownika w ramach konta o identyfikatorze id.
Parametry: jak w liście transakcji powyżej
Odpowiedź: jak w szczegółach transakcji poniżej
Szczegóły transakcji o identyfikatorze id.
Parametry: brak
Odpowiedź:
| id | identyfikator obiektu |
|---|---|
| user-account-id | identyfikator konta |
| amount | kwota w PLN |
| currency-amount | kwota w natywnej walucie |
| balance | saldo po transakcji w PLN |
| currency-balance | saldo po transakcji w natywnej walucie |
| booked-on | data księgowania |
| transaction-on | data transakcji |
| description | przyjazny, "inteligentny" opis transakcji. Preferuj to pole względem title/party/kind/name. |
| title | tytuł transakcji |
| kind | rodzaj transakcji, nazywany czasem "typem operacji" |
| name | opis nadany przez użytkownika |
| category-id | identyfikator kategorii |
| category-name | nazwa kategorii |
| party | druga strona transakcji |
| party-iban | skrót kryptograficzny IBAN-u drugiej strony transakcji |
| iban-checksum | suma kontrolna oryginalnego IBAN-u |
| exclude-from-calculations | czy transakcja jest wyłączona z sumowania do wydatków/przychodów? |
| internal | czy transakcja jest pomiędzy własnymi rachunkami? |
| best-name | nazwa konta 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ą konta) |
| account-name | oficjalna nazwa konta bankowego, którą ewentualnie możesz wyświetlać jako drugorzędną w stosunku do best-name; dla portfeli przyjumuje wartość "Pieniądze w portfelu", ale nie można tego hardkodować (zmienia się) |
| currency-name | trzyliterowa nazwa waluty, np. "PLN" |
Uwaga: nie można polegać na pozostałych zwracanych wartościach. Zostaną one wkrótce usunięte z API. Prosimy bazować wyłącznie na wartościach udokumentowanych powyżej.
Utworzenie transakcji w Portfelu. Użyj tego, aby dodawać do Portfela wydatki i przychody gotówkowe. Nie ma możliwości tworzenia transakcji na zwykłych kontach bankowych.
Parametry:
| money_transaction[user_account_id] | identyfikator portfela; jeśli nie zostanie wysłany, transakcja trafi do portfela domyślnego |
|---|---|
| money_transaction[category_id] | identyfikator kategorii (obowiązkowy) |
| money_transaction[currency_amount] | kwota w natywnej walucie, obowiązkowo dodatnia. Czy jest to wydatek czy przychód gotówkowy 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ę (obowiązkowy) |
| money_transaction[currency_id] | docelowo identyfikator waluty, obecnie 1 (obowiązkowy) |
| money_transaction[direction] | kierunek kwoty, określa czy jest to wydatek czy przychód, przyjmuje wartości "withdrawal" lub "deposit" (obowiązkowy) |
| money_transaction[exclude_from_calculations] | czy transakcja jest wyłączona z sumowania do wydatków/przychodów? Wartości "0" - domyślne, normalna transakcja. "1" - transakcja wykluczona z sumowania |
| money_transaction[internal] | czy transakcja jest pomiędzy własnymi rachunkami? Wartości "0" - domyślne, normalna transakcja. "1" - transakcja między własnymi rachunkami, np. wpłata we wpłatomacie |
| money_transaction[tag_string] | lista tagów oddzielonych spacją |
| money_transaction[title] | tytuł transakcji |
| money_transaction[transaction_on] | data transakcji (obowiązkowy) |
| 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ą. (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. Użyj tego, aby zmodyfikować wydatek lub przychód gotówkowy w Portfelu. Nie ma możliwości modyfikacji transakcji na zwykłych kontach bankowych.
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.
Parametry: brak
Usunięcie transakcji o identyfikatorze id z Portfela. Nie ma możliwości usunięcia transakcji z kont bankowych.
Kategorie
Grupy kategorii z przynależnymi kategoriami. To drzewo kategorii będzie Ci potrzebne w formularzu dodawania i edycji wydatków gotówkowych. Parametr direction pozwala odfiltrować kategorie wydatkowe i przychodowe.
Parametry:
| direction | "deposit" lub "withdrawal" - pokaż tylko kategorie przychodowe lub wydatkowe. Uwaga: nie możesz pozwolić użytkownikowi na przypisanie kategorii przychodowej do wydatku i vice versa. |
|---|
Przykłady
Poniżej zamieszczamy kilka przykładowych żądań API dla użytkownika DEMO.
Konta bankowe i Portfel: https://demo%40kontomierz.pl:demo123@kontomierz.pl/user_accounts.xml
Wszystkie transakcje (strona 1): https://demo%40kontomierz.pl:demo123@kontomierz.pl/money_transactions.xml
Wszystkie transakcje (strona 2): https://demo%40kontomierz.pl:demo123@kontomierz.pl/money_transactions.xml?page=2
Kategorie: https://demo%40kontomierz.pl:demo123@kontomierz.pl/category_groups.xml
Wskazówki implementacyjne
Bezpieczeństwo
Wszystkie żądania API są po HTTPS. Znajdź taką bibliotekę HTTP dla Twojego języka, która bez problemu obsługuje ten protokół.
Zwróć szczególną uwagę na przechowywanie loginu i hasła do Kontomierza w Twojej aplikacji. Zadbaj, by w przypadku kradzieży urządzenia z zainstalowanym klientem API odzyskanie loginu i hasła było maksymalnie utrudnione lub niemożliwe.
Opisy transakcji
Jako opisu transakcji używaj wartości "description". Dbamy, by był to optymalny opis transakcji, dla każdej kombinacji atrybutów "cząstkowych", czyli title, party, kind, name. Uwaga: wszystkie cząstkowe atrybuty są opcjonalne (i bardzo często puste).
Synchronizacja
Klient musi obsługiwać niedostępność sieci i niedochodzenie żądań do serwera.
Przemyśl dobrze model synchronizacji danych pomiędzy Kontomierzem i Twoim klientem. Zauważ, że synchronizacja jest obustronna.
Klient API powinien regularnie pobierać z Kontomierza listę kont bankowych, listę transakcji i drzewo kategorii użytkownika. Wszystkie te elementy mogą się w każdej chwili zmienić (np. użytkownik zdefiniował nową kategorię).
Klient API powinien wysyłać do Kontomierza wydatki i przychody, które użytkownik wprowadził offline. Wydatek wprowadzony offline powinien być wysyłany aż do uzyskania poprawnej odpowiedzi z serwera.
UID / id / client_assigned_id
UID w kliencie API nie jest do niczego przydatny i nie powinieneś go używać. Zostanie w przyszłości usunięty z API. UID to identyfikator transakcji z systemu transakcyjnego banku. Używamy go w Kontomierzu do rozpoznania, czy importowana transakcja jest nowa.
id to bazodanowy identyfikator transakcji. Umożliwi Ci odróżnienie transakcji nowo-pobranych od już-posiadanych w Twojej lokalnej bazie danych.
client_assigned_id to tymczasowy identyfikator generowany przez klienta API dla transakcji dodawanych via API. 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ą.
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
