Разработка интеграции Битрикс24 с системой электронного документооборота

Разработка интеграции Битрикс24 с системой электронного документооборота

Менеджер закрывает сделку в Битрикс24, генерирует договор из шаблона, скачивает PDF, отправляет email юристу, юрист открывает СЭД, загружает файл, запускает маршрут согласования, через три дня пишет менеджеру в мессенджер «согласовано», менеджер вручную меняет стадию сделки. Каждый день. На каждый договор. Интеграция убирает эту цепочку ручных действий — документ уходит в СЭД из карточки сделки, согласование проходит автоматически, статус возвращается в CRM.

С чем интегрируем

На российском рынке четыре основных СЭД, и у каждой — свои особенности API:

Со стороны Битрикс24 интеграция строится на REST API — единственном способе взаимодействия с облачной версией. Для коробочной Битрикс24 доступны события модулей и прямой доступ к БД, но REST предпочтителен для переносимости.

Точки интеграции в Битрикс24

Генерация документов — crm.documentgenerator.*

Набор REST-методов для работы с генератором:

• crm.documentgenerator.document.add — создание документа по шаблону (docx с плейсхолдерами) из данных сделки, контакта, компании
• crm.documentgenerator.document.get — получение документа с метаданными
• crm.documentgenerator.document.list — все документы привязанные к сущности
• crm.documentgenerator.template.list — список доступных шаблонов

Результат генерации — файл (PDF или DOCX), который нужно передать в СЭД.

Битрикс24.Диск — хранение файлов:

• disk.file.upload — загрузка (подписанная версия из СЭД)
• disk.file.get — скачивание
• disk.attachedobject.get — файлы, привязанные к CRM-сущностям

Бизнес-процессы — встроенный механизм автоматизации. Из БП можно отправить HTTP-запрос в СЭД через действие «Webhook-запрос», передав данные документа и инициировав согласование. Это ключевая точка: менеджер двигает сделку на стадию «На согласовании», БП автоматически генерирует документ и отправляет в СЭД.

Архитектура: с middleware или без

Простая интеграция (одна СЭД, линейный маршрут согласования) может обойтись без промежуточного сервиса. Битрикс24 общается с СЭД напрямую: бизнес-процесс отправляет webhook в СЭД, СЭД при смене статуса отправляет webhook обратно в Битрикс24.

Но на практике так бывает редко. Появляются требования: логирование всех операций для аудита, повторные попытки при ошибках, очереди (СЭД отвечает не мгновенно), трансформация форматов данных. Тогда нужен middleware:

Битрикс24                    Middleware                    СЭД
    │                            │                          │
    ├── webhook: сделка ─────────┤                          │
    │   перешла на стадию        │                          │
    │                            ├── Генерация документа    │
    │                            │   (crm.documentgenerator)│
    │                            │                          │
    │                            ├── Отправка в СЭД ────────┤
    │                            │                          │
    │                            │◄── webhook: статус ──────┤
    │                            │    изменён               │
    ├── crm.deal.update ◄────────┤                          │
    │   (стадия сделки)          │                          │
    │                            │◄── файл: подписанная ────┤
    ├── disk.file.upload ◄───────┤    версия                │
    │                            │                          │

Middleware — Laravel, Node.js или Python-сервис. Хранит маппинг document_id (СЭД) → deal_id (Б24), обрабатывает очереди через Redis/RabbitMQ, ведёт лог каждой операции.

Deep-dive: маршруты согласования и маппинг статусов

Согласование — центральный и самый сложный процесс. Маршруты бывают трёх типов:

Последовательный — юрист → финдиректор → гендиректор. Каждый следующий получает документ после одобрения предыдущим. Самый простой для интеграции: статус меняется линейно.

Параллельный — документ уходит нескольким согласующим одновременно. Достаточно одобрения всех (или кворума — например, 3 из 5). Сложнее: нужно отслеживать промежуточные статусы каждого участника.

Условный — маршрут зависит от суммы договора, типа контрагента, подразделения. Договор до 500 000 руб. согласует руководитель отдела, свыше — коммерческий директор плюс юрист. Маршрут конфигурируется в СЭД, но middleware должен корректно обрабатывать любую конфигурацию.

Маппинг статусов. СЭД и Битрикс24 используют разные модели. Таблица соответствий — основа интеграции:

Webhook из СЭД при смене статуса:

POST /api/sed-webhook
{
    "document_id": "DOC-2025-4521",
    "new_status": "approved",
    "approved_by": "[email protected]",
    "timestamp": "2025-03-12T11:45:00+03:00",
    "comments": "Замечаний нет",
    "signed_file_url": "https://sed.company.ru/files/DOC-2025-4521-signed.pdf"
}

Middleware по document_id находит связанную сделку, обновляет стадию через crm.deal.update, загружает подписанный файл через disk.file.upload, добавляет запись в таймлайн через crm.timeline.comment.add: «Договор согласован Петровым И.И. 12.03.2025 11:45».

Если СЭД не поддерживает webhook (старые версии 1С:Документооборота, некоторые конфигурации DocsVision) — используется polling. Агент на стороне middleware опрашивает API СЭД каждые 1-5 минут, проверяя изменения статусов документов.

Конфликты и блокировки

Ситуация: менеджер отредактировал договор в Битрикс24, пока документ на согласовании в СЭД. Если отправить обновлённую версию — согласование нужно перезапустить. Если не отправить — согласованная версия будет отличаться от актуальной.

Три стратегии:

• Блокировка — пока документ на согласовании, редактирование в Б24 запрещено. Реализуется через проверку UF-поля статуса в обработчике события OnBeforeCrmDealUpdate или через ограничение прав на стадии.
• Версионирование — каждое изменение создаёт новую версию, согласование перезапускается. Сложнее технически, но гибче.
• Уведомление — менеджер получает предупреждение. Решение за человеком.

На практике блокировка — самый надёжный вариант. Менеджер видит в карточке сделки статус «На согласовании» и понимает, что редактировать нельзя.

Метаданные документа и юридическое хранение

СЭД хранит не просто файл, а документ с метаданными: номер, дата, тип (договор, акт, счёт-фактура), контрагент, сумма, срок действия, ответственный. При интеграции нужно передать эти метаданные из CRM в СЭД.

Маппинг полей сделки Битрикс24 на карточку документа в СЭД:

Для юридически значимых документов (договоры, акты) СЭД обеспечивает долгосрочное хранение с электронной подписью. Битрикс24 в этом случае — точка входа (создание и инициация), а СЭД — система учёта и хранения. Подписанные экземпляры возвращаются в Б24 как вложения к сделке, но мастер-копия живёт в СЭД.

Виджет в карточке сделки

Чтобы менеджер не переключался между системами, в карточку сделки встраивается виджет через REST placement CRM_DEAL_DETAIL_TAB:

• Текущий статус согласования с визуальным индикатором (зелёный/жёлтый/красный)
• Маршрут: кто уже согласовал, кто сейчас рассматривает, кто следующий
• История: все действия по документу с датами и комментариями
• Ссылка на документ в СЭД (для тех, у кого есть доступ)

Виджет реализуется как встраиваемое приложение Б24 — фронтенд на React/Vue, данные из middleware по REST.

Этапы и сроки

Интеграция CRM с СЭД убирает ручной труд на стыке двух систем. Менеджер работает в Битрикс24 — формирует документ, двигает сделку. Юрист и руководители согласуют в привычной СЭД. Документ проходит маршрут автоматически, статус возвращается в CRM, подписанная версия сохраняется на Диске. Без копирования файлов, без писем «подпишите, пожалуйста», без ручного обновления стадий.