ㅤAPI (Application Programming Interface) — to zestaw gotowych klas, procedur, funkcji, struktur i stałych dostarczanych przez aplikację (bibliotekę, usługę) do wykorzystania w zewnętrznym oprogramowaniu.
ㅤAPI działa jako pośrednik między twórcą aplikacji a dowolnym środowiskiem, z którym aplikacja musi współdziałać.
ㅤFinmap posiada otwarty interfejs API, który może być wykorzystywany przez użytkowników do własnych potrzeb i do konfigurowania indywidualnych integracji z usługą.
ㅤInformacje na temat interfejsu API można wyświetlić w sekcji Ustawienia – Ustawienia firmy, blok – Deweloperzy. Tutaj znajdują się informacje o dokumentacji API
ㅤ
ㅤKlucz API to klucz szyfrujący do uwierzytelniania użytkownika w systemie, podobny do loginu i hasła.
ㅤNasza dokumentacja API jest oparta na zasobach Swagger
ㅤ
ㅤㅤ
ㅤDokumentacja jest podzielona na moduły:
ㅤ
- webhooks – moduł, który pomaga w pracy z webhook
- default – ogólna kontrola stanu sprawności
- currencies – pokazuje, w jakiej walucie można otworzyć firmę
- accounts – praca z kontami
- tags – praca z tagami
- projects – praca z projektami
- categories/income – praca z kategoriami dochodów
- categories/expense – praca z kategoriami wydatków
- customers – praca z klientami
- investors– praca z inwestorami
- creditors – praca z wierzycielami
- debitors – praca z kredytobiorcami
- suppliers – praca z dostawcami
- employees – praca z pracownikami
- owners – praca z właścicielami
- operations/income – praca z transakcjami przychodu
- operations/expense – praca z transakcjami wydatków
- operations/transfer – praca z przelewami
ㅤㅤ
ㅤW przypadku niektórych modułów dostępna jest możliwość ich przeglądania, edytowania, usuwania i dodawania.:
ㅤ
- tags
- projects
- categories/income
- categories/expense
- customers
- investors
- creditors
- debitors
- suppliers
- employees
- owners
ㅤ
ㅤPoprzez następujące moduły możliwe jest tylko dodawanie operacji, które obejmują:
- operations/income
- operations/expense
- operations/transfer
ㅤ
ㅤWyjątkiem jest moduł kont, za pośrednictwem którego można uzyskać jedynie informacje o tym, które konta znajdują się w usłudze
ㅤ
ㅤ
ㅤPrzykłady żądań
ㅤ
ㅤEdytowanie podmiotów
Jak już opisano wcześniej, możliwe jest pobieranie/edytowanie/dodawanie/usuwanie określonych podmiotów, na przykład przeanalizujemy taki podmiot jako tagi
Aby uzyskać informacje o tagach w firmie, musimy użyć funkcji GET
ㅤ
ㅤ
Otwórz tę opcję – Następnie kliknij przycisk Try it our
ㅤ
ㅤ
Następnie wprowadź klucz API i kliknij przycisk – Execute
ㅤ
Następnie otrzymujemy odpowiedź zawierającą id i nazwę tagów, które są dostępne w naszej usłudze (id – będzie potrzebne później do edytowania/usuwania/tworzenia operacji) przykład odpowiedzi:
ㅤ
ㅤ
Dodawanie podmiotów działa w taki sam sposób jak odbieranie danych. Aby dodać podmiot, używamy parametru POST, wykonujemy wszystkie kroki jak w przypadku pierwszego żądania, tylko teraz należy wypełnić pole „label”=”specify the name of the entity” – następnie klikamy Execute – W odpowiedzi otrzymujemy nowy tag
ㅤ
Usunięcie i edytowanie działa na tej samej zasadzie, tylko teraz, aby usunąć lub edytować podmiot, potrzebujemy id, który wcześniej uzyskaliśmy za pomocą parametru GET. Spójrzmy na przykład usuwania, za usuwanie odpowiada parametr DELETE: otwieramy ten parametr – klikamy Try it our – wstawiamy klucz API – id usuwanej podmiotó – i klikamy Execute – w odpowiedzi otrzymamy, że żądanie zakończyło się sukcesem, podmiot został usunięty
ㅤ
ㅤ
Dodawanie operacjiㅤ
Aby dodać płatności, używane są następujące moduły:
- operations/income
- operations/expense
- operations/transfer
ㅤ
Rozważmy przykład modułu operations/income:
Dostęp jest tylko do parametru POST, ponieważ jest on odpowiedzialny za dodawanie danych.
Na początek otwieramy tę opcję – klikamy Try it our – podajemy klucz API – od razu otworzy nam się okno do wpisania informacji
ㅤ
ㅤ
„comment”: „string”, – pole komentarza, niewymagane
„amount”: 0, – pole kwoty, wymagane do wypełnienia
„date”: „current date in utc”, pole z datą płatności, wymagane
„projectId”: „string”, – projekt, niewymagane
„tagIds”: [„string”], – tag, niewymagane
„externalId”: „new uuid v4”, – ten parametr jest generowany automatycznie, niewymagany
„periodStartTimestamp”: 0, – początek okresu, niewymagany
„periodEndTimestamp”: 0, – koniec okresu, niewymagany
„dateOfPayment”: „date”, – data transakcji, opcjonalne
„accountToId”: „string”, – konto, niewymagane
„categoryId”: „string”, – kategoria, niewymagane
„borrowerId”: „string”, – pożyczkobiorca, niewymagane
„creditorId”: „string”, – kredytodawca, niewymagane
„consumerId”: „string”, – klient, niewymagane
„investorId”: „string”, – inwestor, niewymagane
ㅤ
Aby dodać transakcję, wystarczy podać następujące informacje:
„comment”:”test”,
„amount”:123456,
„date”:1675255361458, – pobrać w formacie UTC, skorzystać z usługi https://currentmillis.com/, informacje, których potrzebujemy
ㅤ
ㅤ
„accountToId”:”606ff2357454e1bab63882e3″ – id naszego konta, można go uzyskać za pomocą parametru GET, w bloku konta – po określeniu tych danych, kliknij przycisk Execute – pomyślnie wykonaliśmy żądanie
ㅤ
ㅤ