ㅤ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
