Наш опыт интеграции с Диадок — архитектура исходящего процесса
Введение
Привет, Хабр! Разработчик из АльфаСтрахования снова на связи. Наша скрам команда занимается автоматизацией бизнес-процессов Операционного блока. В основном это разработка приложений, связанных с документооборотом внутри компании. Поэтому одной из тем, которую никак не могли пропустить, была интеграция с Диадок — системой электронного документооборота с контрагентами.
АльфаСтрахование взаимодействует с контрагентами, партнёрами, агентами и другими через различные системы документооборота, включая Диадок. Поскольку электронный документооборот (далее ЭДО) с контрагентами в системе Диадок хорошо соответствовал процессам, разработкой которых команда уже занимается, и у нас имеется опыт взаимодействия с другими внешними системами, решили создать интеграцию между системой электронного документооборота АльфаСтрахование (далее СЭД-АС) и системой Диадок. Об этой интеграции и пойдет речь в данной статье.
Анализ взаимодействия с системой Диадок
Пользовательское взаимодействие
потоки данных
Взаимодействие с системой Диадок команда разделила на два потока: входящий — получение документов, отправленных контрагентом, и исходящий — отправка документов контрагенту или внутреннему сотруднику.
После анализа текущего взаимодействия АльфаСтрахование с системой Диадок, мы разглядели несколько крупных моментов:
Несмотря на наличие различных форматов документооборота, наши сотрудники и контрагенты преимущественно используют неформализованный — передача документов, не привязанных к определенному формату
В системе Диадок можно назначать подписантом документа конкретного сотрудника
Сотрудник, направляющий документы на подписание в систему Диадок, не обязательно будет тем, кто их подпишет от имени АльфаСтрахования
Одной из самых рутинных частей работы для сотрудника — момент переноса файлов ЭДО (файлы подписи, протоколы и так далее) из системы Диадок в СЭД-АС. На этом моменте часто теряются документы
За ЭДО в системе Диадок платит сторона, первой отправляющая подписанный документ
В системе Диадок реализована функциональность передачи контрагенту возможности первым подписывать документ, используя шаблон — предзаполненный документ, не имеющий юридической силы, отправляемый без подписи
Тестовое окружения
окружения в Диадок
В системе Диадок для интегрирующийся организаций нет отдельного тестового окружения с хостом, авторизацией и прочим. Этот момент обыгрывается иначе. В системе создаются тестовые организации, каждую из которых можно настроить, имитируя реальные. Внутри системы Диадок, наверное, существует четкое разделение зон на тестовую и продуктивную, но при взаимодействии визуально как с точки зрения UI, так с точки зрения API, будет казаться, что все находится в одном контуре.
Наша команда создала несколько тестовых организаций, одну из которых считаем АльфаСтрахование в тесте, а остальные — будто контрагенты. На них наигрывали различные вызовы API Диадок.
сообщение
ЭДО в системе Диадок представляет из себя сообщение с документами, которое со временем обрастает патчами в виде действий над этими документами. Мы быстро разобрались, что создание ЭДО в Диадок реализуется относительно просто, вызовом 2-х методов:
Выкладываем документы на полку в Диадок (ShelfUpload)
Создаем сообщение с выложенными документами (PostMessage)
Если сообщение создается не как Шаблон, то добавляем еще одно действие — отправляем сообщение на подпись подписанту (PostMessagePatch), выбранному менеджером со стороны АльфаСтрахование.
Реализация
Вызов интеграции из системы другой команды
Как скрам команда мы двигаемся итерациями.
отправка документов в Диадок из другой команды
Первый тип документов, проходящий через интеграцию, относится к исходящему потоку, поэтому и решили начать с реализации исходящего взаимодействия. За направление этих документов отвечала другая команда.
После совместного обсуждения сформулированы требования в виде пользовательских историй к интеграции.
Я, как вызывающая система, хочу выбирать контрагента по ИНН, КПП и ОГРН
Я, как вызывающая система, хочу назначать подписанта со стороны АльфаСтрахования по его email
Я, как вызывающая система, хочу узнавать о завершении жизненного цикла документов в системе Диадок
Я, как вызывающая система, хочу, чтобы в СЭД-АС загружались документы по завершению их жизненного цикла в системе Диадок
архитектура синхронизации данных об организации
Сразу скажу, на следующих архитектурных рисунках буду опускать ранее нарисованные детали и отображать только изменившиеся элементы для упрощения восприятия картинок.
В начале разработки встал вопрос: «А нужно ли дублировать у себя информацию об организациях в Диадок?». Как видно по рисунку, решили, что нужно. Наша интеграция периодически опрашивает API Диадок. Она забирает оттуда информацию о наших контрагентах и их подразделениях. Также забирает информацию о пользователях, зарегистрированных как сотрудники АльфаСтрахование в системе Диадок. Такое решение позволяет не запрашивать эту информацию каждый раз, когда это необходимо пользователю. Бонусом дает возможность использовать преимущества наших справочников, построенных на OData. API Диадок позволяет нам оперативно получать информацию о новых взаимоотношениях с контрагентами, благодаря чему настроили синхронизацию так:
Данные о сотрудниках раз в час. Реализуем используя метод в API GetEmployees
Данные о новых наших контрагентах и подразделений в них раз в 3 минуты. Реализуем используя метод в API GetCounteragents с использованием afterIndexKey
Данные о всех наших контрагентах и подразделений в них раз в сутки. Реализуем используя методы в API GetCounteragents и GetCounteragent
Такая синхронизация позволила минимизировать лаг времени в обновлениях справочника настолько, что пользователи СЭД-АС его не замечают.
В случае исходящего процесса старт происходит из контура АльфаСтрахование, что значительно упрощает архитектуру взаимодействия.
архитектура отправки документов в Диадок из другой команды
Как видно из рисунка, процесс отправки документов на подписание не сложный. Внешняя команда отправляет запрос в наш сервис. Сервис по присланным данным ищет нужного контрагента, создает сообщение с документами и отправляет его на подписание в Диадок. После чего кладет в базу данных (далее БД) информацию о созданном сообщении для дальнейшего отслеживания.
На схеме также отображен основной минус такого взаимодействия. После создания сообщения для отслеживания завершенности ЭДО документов нужно периодически опрашивать прокси сервис. Куда лучше, если интеграция сама сообщит о завершении по факту наступления этого события.
Из плюсов могу выделить один — для взаимодействия с системой Диадок создали шлюзы (сервисы-прокладки). Это позволило на стороне основных сервисов настроить общение с API Диадок в привычном нам виде. Также это оказалось полезным в ситуациях, когда сотрудники информационной безопасности хотят по-особенному наблюдать за трафиком, а методы наблюдения требуют особенных мер для сервиса.
архитектура отслеживания статусов документов в Диадок
Поскольку сроки реализации маленькие, с отслеживанием статусов ЭДО тоже не заморачивались. Как видно из рисунка, по сути создали один фоновый сервис, который раз в какой-то период времени считывает сообщений из БД, опрашивает по ним Диадок и, если документы имеют завершенные статусы, загружает файлы ЭДО в СЭД-АС и архивирует запись о сообщении в БД.
Основной минус данной реализации — формирование очереди отслеживаемых сообщений в таблице БД. Во-первых, такой подход не масштабируется — вынуждены держать один экземпляр приложения, работающего с таблицей. Во-вторых, в API Диадок есть метод GetDocflowEvents. Этот метод позволяет опрашивать Диадок только по изменившимся сообщениям, а не по всему, что есть в таблице. Мы планируем на него переходить, так как он обеспечивает большую скорость синхронизации статусов документов меньшими затратами.
Вызов интеграции из СЭД-АС
отправка документов в Диадок из СЭД-АС
Теперь предстояло обогатить имеющееся решение так, чтобы использовать его прямо из СЭД-АС. Для этой истории набор требований не сильно отличался:
Я, как менеджер, хочу отправлять документы на подписание в Диадок, не выходя из СЭД-АС
Я, как менеджер, хочу видеть в СЭД-АС статусы ЭДО, отправленного в Диадок
Я, как менеджер, хочу назначать подписанта со стороны АльфаСтрахования
Я, как менеджер, хочу отправлять документы в конкретное подразделение контрагента
Я, как менеджер, хочу, чтобы файлы ЭДО (файлы подписи, протоколы и т.д.) сами загружались в СЭД-АС
Если отойти от требований, то хотели выстроить примерно следующую картину. Менеджер открывает СЭД-АС, выбирает контрагента и подписанта со стороны АльфаСтрахование. Затем отправляет документы в систему Диадок на подписание. Пока менеджер занимается прочими делами интеграция подтягивает статус ЭДО в СЭД-АС. И как только в системе Диадок жизненный цикл документов будет завершен (их подпишут или отклонят), интеграция загрузит в СЭД-АС всю необходимую информацию по ЭДО. С этого момента менеджер уже привычными средствами в СЭД-АС сможет увидеть, что по его документам работа в Диадок окончена, что ускорит принятие решений по дальнейшим его действиям.
Форма отправки документов в Диадок
Для отправки документов из СЭД-АС в систему Диадок создали специальную форму, на которой менеджер может выбрать нужные ему пункты. Ранее решили дублировать информацию о контрагентах и подписантах в наши справочники, что упростило реализацию вывода предложений для автозаполнения полей при наборе символов.
Еще можно заметить, что на форме не оперируем такими словами как Шаблон. Казалось, что это запутает пользователя, и просто написали какая сторона первая будет подписывать документы в ЭДО.
В архитектуре взаимодействия с интеграцией так же появились изменения. Так получилось, что между предыдущей и этой реализациями в компании активно развивалось взаимодействие через корпоративную Кафка. И наша команда научилась ей пользоваться. Поэтому решили добавить её использование к интеграции. Теперь при отправке документа на подписание указывается топик Кафка. При завершении жизненного цикла в него отправится информация по ЭДО.
Старт процесса из СЭД-АС имеет свои специфические особенности, поэтому по завершению ЭДО добавили сервис «Служба синхронизации специфичных для процесса данных в СЭД-АС», учитывающий их.
Результат
Интеграция постепенно набирает обороты в компании, но еще есть куда расти. На сегодняшний день через интеграцию в систему Диадок отправлены документы более 200 000 раз.
Так как данные собраны в середине августа 2024 года, то за 3-й квартал 2024 года они не полные. Но как видно по графику основной тренд на рост количества ЭДО создаваемых через интеграцию. Это закономерная картина, ведь со временем все больше и больше разных команд в нашей компании подключаются к отправке документов через нашу интеграцию.
Вывод
По опыту создания различных интеграций ко внешним системам, можем сказать, что у Диадок довольно богатое и хорошее API, хоть и не все методы очевидны и понятны на 1-й взгляд. Он обладает достаточной функциональностью чтобы создать интеграцию автоматизирующую процессы Операционного блока в части взаимодействия с Диадок.
От себя добавлю, документация системы Диадок находиться на хорошем уровне, а также в её API есть интересные решения, которые я могу перенять для будущих проектов. Ну и просто интересно наблюдать на сколько сильно могут отличаться взаимодействия у разных внешних систем, с которыми нужно дружить наш СЭД-АС.
