В цій інструкції ми розглянемо АПІ-документацію 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 – В нас успішно виконується запит
Приклад операції в сервісі, яка була передана через АПІ
