Единый сервис подписания документов через Контур.Диадок для девелопера

Заказчик это девелоперская компания. Документы на подпись у неё создаются в разных внутренних системах, а подписываются через систему электронного документооборота Контур.Диадок. Компании нужен был внутренний сервис, через который все эти системы отправляют документы на подпись, узнают статус подписания, получают подписанные файлы обратно и где хранится архив.

Сервис сделали с нуля. Бэкенд-разработчики Фортех работали в команде заказчика вместе с аналитиками, тестировщиком и руководителем проекта. Проект шёл с января 2024 по декабрь 2025 года, почти два года, и завершился успешно. Поддержку сервиса дальше ведут внутренние сотрудники заказчика.

Задача

• принимать документы от смежных систем и проверять их;
• сохранять документы в S3-хранилище и передавать их в Контур.Диадок;
• опрашивать статусы документов в Диадоке и загружать обновления;
• возвращать обновления и подписанные документы в смежные системы;
• получать данные об организациях из MDM;
• разграничить доступ по ролям.

Ограничения задачи

Сервис работает между несколькими внутренними системами и внешним Диадоком, поэтому у каждого способа связи свой протокол: HTTP, gRPC и Kafka.

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

Инфраструктура заказчика в SberCloud и Kubernetes, хранилище файлов S3-совместимое на MinIO.

Решение

Архитектура. Сервис разбили на микросервисы. Компоненты построены на принципе инверсии зависимостей (IoC), поэтому их можно переиспользовать в соседних сервисах заказчика.

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

Путь документа. Сервис получает документ от смежной системы и проверяет его, сохраняет в S3, передаёт в Контур.Диадок, опрашивает статус, загружает обновления и возвращает их вместе с подписанными документами обратно в смежные системы.

События. Через Kafka сервис сообщает смежным системам об изменениях в документообороте. Данные об организациях приходят из MDM по REST и через Kafka.

Очереди. Для фоновых задач внедрили очереди на Redis Bull.

Доступ. Ролевую модель сделали на Keycloak: права проверяются по scope-permissions в RPT-токенах.

Порядок в хранилище. Сервис сам удаляет неиспользуемые и устаревшие данные и файлы из базы и S3-хранилища.

Наблюдаемость и тесты. Написали собственные механизмы сбора метрик и unit-тесты на ключевую бизнес-логику. Для фронтенда сделали отдельные эндпоинты.

У девелопера появился единый сервис подписания документов. Внутренние системы больше не подключаются к Диадоку каждая отдельно: они отправляют документы в один сервис и получают от него статусы и подписанные файлы.

Сервис принимает документы по HTTP и gRPC, сообщает об изменениях через Kafka, хранит архив в S3 и сам чистит устаревшие файлы. Доступ разграничен по ролям через Keycloak.

Проект занял почти два года и завершился успешно, сервис передан на поддержку внутренней команде заказчика.

Частые вопросы

Зачем отдельный сервис подписания, если у компании уже есть Диадок?
Когда документы создаются в нескольких системах, каждой пришлось бы отдельно подключаться к Диадоку и следить за статусами. Один сервис забирает это на себя: системы отправляют документ и получают результат, не зная, как устроен обмен с Диадоком.

Как держать статусы подписания актуальными во всех системах?
Опрашивать статусы в отдельном фоновом сервисе и рассылать изменения через брокер сообщений. Здесь этим занимаются worker-микросервис и Kafka.

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

Сколько разработчиков нужно на такой проект?
Здесь работали два бэкенд-разработчика вместе с аналитиками, тестировщиком и руководителем проекта. Состав подстраивали под объём работы: второго бэкенд-разработчика подключали, когда он был нужен.