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

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

Коли компанія працює у Бітрікс24 як у CRM і водночас використовує СЕД для внутрішнього документообігу, виникає розрив: договір формується у CRM, а узгодження проходить в іншій системі. Менеджер копіює файл, відправляє на узгодження, чекає відповіді, вручну оновлює статус угоди. Інтеграція усуває цей розрив — документи синхронізуються автоматично, узгодження запускається з CRM, статуси оновлюються в обидві сторони.

Ландшафт СЕД: з чим інтегруємо

На російському ринку домінує кілька систем електронного документообігу:

Зі сторони Бітрікс24 інтеграція будується на REST API — єдиному офіційному способі взаємодії з хмарною версією. Для коробочної версії доступні також подіїї модулів та прямий доступ до бази даних, але REST залишається переважним варіантом для портативності рішення.

Точки інтеграції у Бітрікс24

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

REST API Бітрікс24 надає набір методів для роботи з генератором документів:

• crm.documentgenerator.document.add — створення документа за шаблоном
• crm.documentgenerator.document.get — отримання документа з його властивостями
• crm.documentgenerator.document.list — список документів сутності
• crm.documentgenerator.template.list — доступні шаблони

Документ генерується на основі шаблону (docx з плейсхолдерами) та даних з CRM-сутності (угода, контакт, компанія). Результат — готовий файл, який потрібно передати в СЕД для узгодження.

Зберігання файлів — Бітрікс24.Диск

Усі документи зберігаються на Бітрікс24.Диску. REST-методи:

• disk.folder.getchildren — вміст папки
• disk.file.upload — завантаження файла
• disk.file.get — отримання файла
• disk.attachedobject.get — привʼязані до сутностей файли

Через Диск можна організувати версіонування: кожна ітерація узгодження — нова версія файла з коментарем про внесені зміни.

Бізнес-процеси Бітрікс24

Вбудовані бізнес-процеси (БП) запускаються на угодах, лідах та елементах списків. Дії БП:

• Сповіщення працівника
• Затвердження / відхилення
• Зміна полів сутності
• Виклик webhook / REST-запит

Останній пункт — ключовий для інтеграції. З бізнес-процесу можна відправити HTTP-запит у СЕД, передавши дані документа й ініціюючи процес узгодження.

Архітектура інтеграції

Типова схема взаємодії:

Бітрікс24                   Middleware                    СЕД
    │                            │                          │
    ├── Створення документа ─────┤                          │
    │                            ├── Відправлення на        │
    │                            │   узгодження ──────────────┤
    │                            │                          │
    │                            │◄── Webhook:              │
    │                            │    статус змінений ──────┤
    ├── Оновлення статусу ◄──────┤                          │
    │   угоди                    │                          │
    │                            │◄── Файл: підписаний ────┤
    ├── Завантаження файла ◄─────┤    версія               │
    │   на Диск                  │                          │

Middleware — проміжний сервіс (Laravel, Node.js, Python), який виконує кілька функцій:

• Трансформація форматів даних між API двох систем
• Обробка черг (СЕД може відповідати не миттєво)
• Логування всіх операцій для аудиту
• Обробка помилок та повторних спроб

Можна обійтися без middleware, якщо інтеграція проста (одна СЕД, лінійний процес). У цьому випадку Бітрікс24 спілкується з СЕД прямо через webhook-обробники.

Deep-dive: маршрути узгодження та синхронізація статусів

Узгодження документів — центральний процес інтеграції й одночасно найскладніший. Розберемо його детально.

Типи маршрутів узгодження:

• Послідовний — документ проходить по ланцюжку: юрист → фінансовий директор → генеральний директор. Кожний наступний учасник отримує документ тільки після одобрення попередним.
• Паралельний — документ відправляється кільком узгоджуючим одночасно. Достатньо одобрення всіх (або більшості, залежить від налаштування).
• Умовний — маршрут залежить від параметрів документа. Договір до 100 000 рублів узгоджує керівник відділу, вище — комерційний директор.

Маппінг статусів. СЕД та Бітрікс24 використовують різні моделі статусів. Потрібна таблиця відповідностей:

Синхронізація в реальному часі. Оптимальний варіант — webhook-сповіщення з СЕД при кожній зміні статусу. Якщо СЕД не підтримує webhooks (наприклад, старі версії 1С:Документообігу), використовується polling — періодичний опит API з інтервалом 1-5 хвилин.

Обробник webhook на стороні middleware:

POST /api/sed-webhook
{
    "document_id": "DOC-2024-1234",
    "new_status": "approved",
    "approved_by": "[email protected]",
    "timestamp": "2024-03-15T14:30:00+03:00",
    "comments": "",
    "signed_file_url": "https://sed.company.ru/files/DOC-2024-1234-signed.pdf"
}

Middleware по document_id знаходить пов'язану угоду у Бітрікс24 (маппінг зберігається в базі), оновлює стадію через crm.deal.update, завантажує підписаний файл через disk.file.upload, додає коментар у таймлайн угоди через crm.timeline.comment.add.

Обробка конфліктів. Ситуація: менеджер змінив документ у Бітрікс24, поки той перебував на узгодженні у СЕД. Стратегії:

• Блокування — поки документ на узгодженні, редагування у Б24 заборонено (через права доступу або валідацію в обробнику подіїї)
• Версіонування — кожна зміна створює нову версію, узгодження перезапускається
• Сповіщення — менеджер отримує попередження, рішення приймається вручну

На практиці частіше за все застосовується блокування — це простіше в реалізації й зрозуміліше користувачам.

Сповіщення та прозорість процесу

Критично важливо, щоб учасники процесу бачили актуальний статус без перемикання між системами. Реалізується через:

• Сповіщення у Б24 (im.notify.system.add) — при кожній зміні статусу у СЕД
• Користувальницьке поле угоди — «Статус узгодження» з історією змін
• Коментарі в таймлайні — автоматичний запис «Документ узгоджений Іванівим І.І. 15.03.2024 14:30»
• Віджет у карточці угоди (вбудовування через placement) — відображення поточного маршруту з візуальним індикатором прогресу

Етапи реалізації

Інтеграція CRM та СЕД усуває ручну роботу на стику двох систем. Менеджер працює у Бітрікс24, узгоджуючі — у знайомій СЕД, а документ проходить маршрут автоматично.