В этой инструкции мы рассмотрим API-документацию Finmap, где можно найти эту информацию и каковы ее особенности.
API (Application Programming Interface) – это набор готовых классов, процедур, функций, структур и констант, предоставляемых приложением (библиотекой, сервисом) для использования во внешних программных продуктах.
API выступает посредником между разработчиком приложений и любой средой, с которой это приложение должно взаимодействовать.
В сервисе денежного учета представлен открытый API, который могут использовать пользователю для собственных потребностей и настройки личных интеграций с сервисом.
Просмотр информации по API можно в Настройках, пункт Разработчикам
Здесь вы найдете информацию об API-документации
Ключ 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
После этого вставляем API ключ – и нажимаем на кнопку – Execute
После этого мы получаем ответ, где будут указаны id, и название тегов, которые есть в нашем сервисе (id — понадобится позже, для редактирования/удаления/создание операции) пример ответа:
Добавление сущностей работает по такому же принципу, как получение данных. Чтобы добавить сущность используем параметр POST, делаем все шаги, как с первым запросом, только теперь необходимо будет заполнить поле «label»=»указываем название сущности» — после этого нажимаем Execute — В ответ мы получаем новый тег
Удаление и редактирование работает по такому же принципу, только теперь чтобы удалить или редактировать сущность, нам и понадобится id, которое мы раньше получали с помощью параметра GET. Рассмотрим на примере удаления, за удаление у нас отвечает параметр DELETE: Открываем этот параметр – нажимаем Try it our – Вставляем API ключ – id сущности, которую необходимо удалить – и нажимаем Execute – в ответ мы получим, что запрос удачен, сущность была удалена
Добавление операций
Для того чтобы добавить платежи, используются блоки :
- operations/income
- operations/expense
- operations/transfer
Рассмотрим пример с блоком operations/income:
Доступ только к параметру POST, ведь именно он отвечает за добавление
Для начала открываем этот параметр – нажимаем Try it our – указываем API ключ – Нам сразу будет открыто окно для указания информации
«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 — У нас успешно выполняется запрос
