ㅤAPI (Application Programming Interface) — це набір готових класів, процедур, функцій, структур і констант, що надаються додатком (бібліотекою, сервісом) для використання в зовнішніх програмних продуктах.
ㅤAPI виступає посередником між розробником додатків і будь-яким середовищем, з яким цей додаток повинен взаємодіяти.
ㅤУ Finmap відкритий АПІ, який можуть використовувати юзери для власних потреб і налаштування індивідуальних інтеграцій з сервісом.
ㅤПереглянути інформацію по АПІ можна у розділі Налаштування – Налаштування компанії, блок – Розробникам. Тут ви знайдете інформацію про АПІ-документацію
ㅤ
ㅤКлюч 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 – В нас успішно виконується запит
ㅤ
ㅤ
Приклад операції в сервісі, яка була передана через АПІ
ㅤ
ㅤ
Редагування/видалення операцій
ㅤ
Редагувати, або видаляти платежі можна лише в API 2.2. Ці дії можна зробити для платежів:
– Витрат
– Доходів
– Переказів
ㅤ
Щоб це зробити потрібно обрати параметр PATH (редагування), DELETE (видалення) для:
- operations/income
- operations/expense
- operations/transfer
ㅤ
ㅤ
Запит виконується використовуючи externalid (цей параметр можна вказати самостійно при створенні операції) або operationid (цей параметр автоматично створюється при додаванні платежу, його можна отримати через вебхуки, або використавши консоль розробника)
ㅤ
Приклад: Редагуємо платежі через externalid.
При створенні платежу доходу вказуємо externalid
ㅤ
ㅤ
В сервісі створився наступний платіж:
ㅤ
ㅤ ㅤ
Далі обираємо параметр PATH by externalid, та вказуємо в ньому ІД, яке раніше додавали до платежу, та змінюємо суму із 100 на 444, та натискаємо виконати умову:
ㅤ ㅤ
ㅤ
Результат: сума платежу в сервісі змінилася
ㅤ
ㅤ
Видалення платежів працює по такому ж самому принципу, лише потрібно використати інший параметр DELETE
