Опыт интеграции с МоеДело

29.03.2022

На работе поступила заявка на интеграцию нашей облачной кассы с сервисом МоеДело. После недолгих выяснений, переговоров и разработки она была сделана.

МоеДело - учетный онлайн сервис для малого и среднего бизнеса, включающий в себя налоговый, бухгалтерский, кадровый, торговый и финансовые учеты.

Документация

Документация обширная, разбита на несколько уровней, что удобно в навигации, можно вверху в поле api_key вставить свой ключ из ЛК и тестировать запросы, удобно (только я не сразу догадался).

Не все сущности описаны, пришлось обращаться за разъяснениями в компанию, но при наличии возможности тестирования API прямо в документации, можно самому выяснить что есть что.

Запуск запроса к API МоеДело на странице документации
Запуск запроса к API МоеДело на странице документации

Стиль именования имеет отличия от раздела к разделу, видимо микросервисная архитектура, и микросервисы писали разные люди без стандартов именования.

Например запрос /stockorders/api/v1/CustomerOrders/GetList который возвращает список сущностей, для передачи параметров вывода принимает POST данные, а запрос /accounting/api/v1/purchases/waybill принимает больше данных для вывода списка, но через GET параметры. Также заметна разница правил именования от раздела к разделу.

При просмотре документации взял для себя на заметку, что запрос на чтение может быть с методом POST, в тело которого записываются параметры чтения (пагинация, сортировка, фильтрация), что делает адресную строку чище (но противоречит семантике REST FULL?).

Процесс

В API МоеДело отсутсвуют WebHook'и, поэтому если МоеДело рассматривается в качестве источника информации для обработки на стороннем сервисе, тогда нужно опрашивать сервер МоеДело, что не всегда удобно, к тому же существуют ограничения на частоту запросов (при тестировании не удалось уперется в лимиты).

Интеграция с МоеДело возможна только при наличии внешнего сервера, который будет работать с API МоеДело по http.

Кроме пользовательской интеграции есть партнерская интеграция, которая позволяет пользователям МоеДело автоматически подключать готовые интеграции, передавая от пользователя в интеграцию авторизационные данные.

В целом процесс использования API МоеДело оказался довольно простым. PHP клиент из обыденной моей схемы легко уложился.

Файловая структура PHP клиента для API МоеДело (одна из первых версий)
Файловая структура PHP клиента для API МоеДело (одна из первых версий)

Техническая поддержка

На мой первый вопрос в онлайн чате в личном кабинете ответили в течении нескольких минут - продлили мне пробный период. Но затем, все мои вопросы в этом же чате были проигнорированы, вообще полностью. При этом смешно получается, в момент когда отправляю сообщение в чат, бот информирует о том, что получу ответ в течении 5 минут, а через 2 часа бот закрывает мой запрос с просьбой оценить качество обслуживания :)

Онлайн чат МоеДело
Онлайн чат МоеДело

Переписка с support по почте тоже для терпеливых ... ответ на вопрос пришлось ждать 5 дней:

Переписка с support МоеДело - ответ бота
Переписка с support МоеДело - ответ бота
Переписка с support МоеДело - видимо кто-то сделал редирект моего исходного письма
Переписка с support МоеДело - видимо кто-то сделал редирект моего исходного письма
Переписка с support МоеДело - долгожданный и неочевидный ответ
Переписка с support МоеДело - долгожданный и неочевидный ответ

Однако, созвоны между руководящими лицами, прошли более успешно.

Итог

В целом интеграция прошла легко, несмотря на возникшие по ходу дела препятствия в плане неопределенности понимания некоторых данных, но это можно самостоятельно решить, применив немного терпения.

На данный момент интеграция находится на начальном этапе, и мне еще предстоит процесс ее доработки (после того как наверху договорятся), так что возможно статья дополнится информацией.