Що таке АПІ у Finmap? Як працювати з даним інструментом

В цій інструкції ми розглянемо АПІ-документацію Finmap, де можна знайти цю інформацію та які її особливості.

API (Application Programming Interface) — це набір готових класів, процедур, функцій, структур і констант, що надаються додатком (бібліотекою, сервісом) для використання в зовнішніх програмних продуктах.

API виступає посередником між розробником додатків і будь-яким середовищем, з яким цей додаток повинен взаємодіяти.

У сервісі фінансового обліку представлений відкритий АПІ, який можуть використовувати юзеру для власних потреб і налаштування індивідуальних інтеграцій з сервісом.

Переглянути інформацію по АПІ можна у Налаштуваннях, пункт Розробникам

Тут ви знайдете інформацію про АПІ-документацію

Ключ API – це ключ шифрування для автентифікації користувача в системі, за аналогією логіну та паролю.

Наша АПІ документація створена на базі ресурсу Swagger, та має наступний вигляд:

Документація розділена на блоки:

  • webhooks – блок який допомогає працювати із вебхуками
  • default – загальна перевірка на працездатність
  • currencies – показує в якій валюті можна відкрити компанію
  • accounts – робота із рахунками
  • tags – робота із тегами
  • projects – робота із проектами
  • categories/income – робота із категоріями доходу
  • categories/expense  – робота із категоріями витрати
  • customers – робота із клієнтами
  • investors– робота із інвесторами
  • creditors – робота із кредиторами
  • debitors – робота із позичальниками
  • suppliers – робота із постачальниками
  • employees – робота із співробітниками
  • owners – робота із власниками
  • operations/income – робота із операціями доходу
  • operations/expense – робота із операціями витарт
  • operations/transfer – робота із переказами

Для певних блоків доступна можливість – перегляду, редагування, видалення, додавання, до таких блоків відносяться:

  • tags 
  • projects 
  • categories/income 
  • categories/expense 
  • customers 
  • investors
  • creditors 
  • debitors 
  • suppliers 
  • employees 
  • owners 

Через наступні блоки є можливість тільки додавати операції, то них належать:

  • operations/income
  • operations/expense
  • operations/transfer

Виключенням є блок accounts,  через цей блок можна лише отримувати інформацію про те, які рахунки є в сервісі

Приклади запитів

Редагування сутностей

Як описувалося раніше, отримувати/редагувати/додавати/видаляти є можливість для певних сутностей, на прикладі будемо розбирати таку сутність, як tags 

Щоб отримати інформацію про те, які в компанії є теги, нам необхідно використати параметр GET

Відкриваємо цей параметр – Далі натискаємо на кнопку Try it our 

Після цього вставляємо АПІ ключ – та натискаємо на кнопку – Execute

Після цього ми отримуємо відповідь, де будуть вказані id, та назва тегів, які є в нашому сервісі(id – знадобиться пізніше, для редагування/видалення/створення операції) приклад відповіді:

Додавання сутностей працює по такому ж самому принципі, як отримання даних. Для того, щоб додати сутність використовуємо параметр POST, робимо всі кроки, як із першим запитом, тільки тепер необхідно буде заповнити поле “label”=”вказуємо назву сутності” – після цього натискаємо  Execute – В відповідь ми отримуємо новий тег

Видалення, та редагування працює по такому ж самому принципі, тільки тепер щоб видалити чи редагувати сутність, нам і знадобиться id, яке ми раніше отримувала за допомогою параметра GET. Розглянемо на прикладі видалення, за видалення в нас відповідає параметр DELETE: Відкриваємо цей параметр – натискаємо Try it our – Вставляємо АПІ ключ – id сутності, яку необхідно видалити – та натискаємо Execute – в відповідь ми отримаємо, що запит вдалий, сутність була видалена 

Додавання операцій

Для того, щоб додати платежі, використовуються блоки :

  • operations/income
  • operations/expense
  • operations/transfer

Розглянемо приклад із блоком operations/income:
Доступ є тільки до параметра POST, адже саме він відповідає за додавання
Для початку відкриваємо цей параметр – натискаємо Try it our – вказуємо АПІ ключ – Нам відразу буде відкрито вікно для вказання інформації

“comment”: “string”, – поле коментар, не обов’язкове для заповнення
“amount”: 0, – поле сума, обов’язкове для заповнення
“date”: “current date in utc”, поле із датою платежу,  обов’язкове для заповнення
“projectId”: “string”, – проект, не обов’язкове для заповнення
 “tagIds”: [“string”], – тег, не обов’язкове для заповнення
“externalId”: “new uuid v4”, – цей параметр автоматично формується, не обов’язкове для заповнення
“periodStartTimestamp”: 0, – початок періоду, не обов’язкове для заповнення
“periodEndTimestamp”: 0, – кінець періоду, не обов’язкове для заповнення
“dateOfPayment”: “date”, – дата угоди, не обов’язкове для заповнення
“accountToId”: “string”, – рахунок, не обов’язкове для заповнення
  “categoryId”: “string”, – категорія, не обов’язкове для заповнення
  “borrowerId”: “string”, – позичальник, не обов’язкове для заповнення
  “creditorId”: “string”,  – кредитор, не обов’язкове для заповнення
  “custumerId”: “string”, – клієнт, не обов’язкове для заповнення
  “investorId”: “string” – інвестор,не обов’язкове для заповнення

Щоб додати операцію, на достатньо буде вказати наступні дані:
“comment”:”тест”,
“amount”:123456,
“date”:1675255361458,
– беремо в форматі UTC, використовуємо сервіс https://currentmillis.com/, необхідна нам інформація 


“accountToId”:”606ff2357454e1bab63882e3″ – id нашого рахунку, можна дістати за допомогою параметру GET, в блоці account – після того, як ми вказали ці дані, натискаємо на кнопку Execute – В нас успішно виконується запит

Приклад операції в сервісі, яка була передана через АПІ