Опыт использования Мегаплан API

До этого я никогда не сталкивался с CRM "Мегаплан" и не знал, что она существует. Один мой хороший знакомый предложил мне подработку, сказал, что один его знакомый ищет программиста, чтобы написать небольшую программу или скрипт для автоматизации работы.
Было сказано, что нужно из какой-то системы получить данные по API, обработать их и вывести в XLS. Мне предложение показалось интересным, я созвонился с Заказчиком и договорился о встрече.

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

Постановка задачи

Заказчик — предприятие, в котором примерно 50 сотрудников.

Сотрудники, проекты и задачи заведены в CRM.

Сотрудники выполняют поставленные задачи. При этом в комментариях к задаче они указывают количество отработанных часов. Кроме того, при выполнении задачи тратятся "ядро-часы" (часы машинного времени).

Они также указываются в каждой задаче в отдельном поле.

Заказчику нужно формировать отчёт в XLS по данным из Мегаплана за указанный временной период.

По каждому проекту, по каждой задаче, нужно знать, сколько было потрачено рабочих часов и "ядро-часов".

Т.е. затраты группируются вначале по проектам, далее по задачам, потом уже по каждому сотруднику.

Примерный вид отчёта представлен на рисунке ниже.

Получить такой отчёт средствами Мегаплана заказчик не смог. Поэтому было принято решение пригласить стороннего разработчика для разработки программы/скрипта, который решит задачу.

Срок: 1 неделя.
Цена: 20 тыс.руб.

Бюджет небольшой, информации в Интернете об опыте использования Мегаплан API — ещё меньше. Нашёл здесь, на Хабре, вот эту статью ^[1], и она совсем не вызывала оптимизма. Пахло проблемами, деньги были не сильно нужны, но было интересно и хотелось помочь людям в их рутине. Я согласился.

Выбор скриптового языка и библиотеки для работы с Мегаплан API

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

Однако проблемы с API начались с самого начала. Выяснилось, что для каждого запроса нужно
вычислять значение X-Authorization header-а по некоторому алгоритму.

Т.е. просто изучать API с помощью curl или httpie не получится.

Соответственно, я понял, что нужно "срезать угол" и поискать какую-нибудь готовую библиотеку для работы с Мегаплан API. Меня интересовали, в основном, библиотеки для Python и Javascript. На github я нашёл следующие библиотеки ^[2]. Большинство из них — это мёртвые проекты, есть ещё много "поделок" на PHP.

Выбирать долго не пришлось, я остановился на библиотеке для языка javascript
megaplanjs ^[3].

Во-первых, я использую javascript каждый день для frontend.

Во-вторых, было интересно разработать что-нибудь для командной строки на javascript.
В-третьих, я смог быстро установить библитеку (спасибо npm), скопировать пример из
документации и… моё приложение уже может аутентифицироваться в Мегаплане и
получать список проектов. Ура!

Обнаруженные проблемы с Мегаплан API

• Проблема с изучением/исследованием API. Для каждого запроса нужно вычислять значение X-Authorization header-а по некоторому алгоритму. Об этом я уже писал выше.
• Ограничение API: частота запросов к API ограничена (50 * N) запросами в минуту, где N — число лицензий.
• Постраничное чтение данных. Проекты, комментарии к проектам, задачи, комментарии к задачам нужно получать постранично. При этом библиотека megaplanjs оказалась к этому не готова и молча возвращала мне лишь первые 50 шт. Мне пришлось самостоятельно допиливать библиотеку.
• Расширенные (custom) поля задач. Ядро-часы, о которых я говорил выше, являлись user-defined (custom) полем задачи. Я не смог их получить через API. Пришлось обращаться в службу поддержки. Там мне подсказали незадокументированный способ их получить. При этом мне пришлось для каждой задачи сделать дополнительный запрос, чтобы получить значение этого поля.
• Ошибка с Task.TimeUpdated. В API есть возможность получить список задач, которые были обновлены (updated) после определённого момента времени. Кстати, нет позможности получить задачи обновлённые/изменённые до определённого момента. Так вот, оказывается, что получение списка задач, обновленных после указанного времени, работает неправильно. Например, если к задаче был добавлен комментарий, в котором указано, что сотрудник потратил X часов на задачу, то это не приводит к изменению времени обновления задачи. Поэтому мне пришлось выбирать через API все задачи и фильтровать их самостоятельно по полю задачи activity — времени последней активности по задаче.

Чем дело закончилось и выводы

Я смог решить поставленную задачу, но потратил на неё намного больше времени, чем планировал.

Это время не оплачивалось, заказчику просто нужен был результат. Как он достигается, ему не интересно.

Раза 3 я обращался в службу поддержки. Не сразу, но помогли. Спасибо.

Тем разработчикам, которые только подумывают заняться subj-ем, я рекомендую лучше оценивать свои риски и закладывать больше времени на разработку.

Сейчас у Мегаплана появилась новая версия API — версия 3 (я использовал версию 1, версии 2 не было?). Я посмотрел версию 3, не нашёл того, что мне было нужно (проекты, задачи, сотрудники). Может быть, версия 3 — это просто дополнение к версии 1, а не замена. Ещё читал, что обещали упростить работу с API — не нужно будет формировать для каждого запроса X-Authorization header.

Исходный код своего скрипта я выложил на github ^[4].
Если понадобится, его можно использовать в качестве примера для быстрого старта своего приложения.

Всем удачной разработки, happy coding!

Автор: azakharo

Источник ^[5]