Інтеграція Бітрікс24 з сервісами електронного підпису

Інтеграція Bitrix24 з сервісами електронного підпису

Встановлювати CryptoPro CSP на кожен ноутбук у компанії, розповсюджувати токени, ловити баги Browser plug-in після кожного оновлення Chrome — не єдиний шлях. Хмарні сервіси електронного підпису знімають прив'язку до робочого місця й дозволяють вибудувати маршрути підписання з кількома учасниками, включаючи контрагентів.

Який сервіс для якого завдання

Для обміну формалізованими документами (УПД, рахунків-фактур) з російськими контрагентами — Diadoc або SBIS. Для внутрішнього підписання без токенів — CryptoPro DSS. Для міжнародних контрактів — DocuSign.

Архітектура інтеграції: як це працює всередині

Загальна схема однакова для всіх сервісів, відрізняється лише API:

1. Документ формується у Bitrix24 через генератор документів (crm.documentgenerator)
2. Обробник витягує файл через REST API Bitrix24 і передає його сервісу ЕП
3. Сервіс запускає маршрут підписання — сповіщає підписантів
4. Підписанти працюють у інтерфейсі сервісу ЕП (або мобільній програмі)
5. Webhook від сервісу повідомляє про завершення
6. Підписаний документ + файл підпису завантажуються назад у Bitrix24

Зв'язуючою ланкою є серверний обробник (приймач webhook). В простому варіанті — PHP-скрипт на хостингу. Для надійної роботи при високому навантаженню — черга завдань через Redis або RabbitMQ з гарантованою доставкою і повторними спробами при помилках.

Інтеграція з Kontur.Diadoc: повний цикл

Diadoc — найбільший оператор ЕДО в Росії, і саме з ним найчастіше пов'язують Bitrix24. REST API доступен за адресою https://api.kontur.ru/diadoc/v1/. Розберемо реалізацію детально.

Аутентифікація. Двохетапна: спочатку POST /Authenticate з логіном/паролем або сертифікатом, потім отриманий токен передається в заголовку Authorization: DiadocAuth ddauth_api_client_id={client_id}, ddauth_token={token}. Токен живе 1 годину. В middleware кешуємо його й оновлюємо автоматично за 5 хвилин до закінчення — інакше запити почнуть падати з 401 посередині робочого дня.

Відправка документа на підпис:

1. Отримати файл з Bitrix24: crm.documentgenerator.document.get
2. Визначити ящик організації: GET /GetMyOrganizations
3. Знайти контрагента у Diadoc: GET /GetCounteragent?myOrgId={id}&counteragentOrgId={id}
4. Для формалізованих документів (УПД, акт, рахунок-фактура) — POST /GenerateTitleXml, Diadoc вимагає XML у форматі ФНС
5. Відправити: POST /PostMessage з вкладеним документом і типом

Для неформалізованих документів (контракти, додаткові угоди) XML не потрібен — файл передається як є.

Відстеження статусу. Diadoc підтримує два механізми:

• Polling — GET /GetDocflowEvents?afterEventId={id} — отримання подій після вказаного ID
• Webhook-підписки — сповіщення при зміні статусу через партнерський доступ

На практиці webhooks Diadoc можуть затримуватися на хвилини при пікових навантаженнях. Надійна схема: webhook як триггер негайної перевірки, polling кожні 5 хвилин як страховка. Так не втрачаються події й не навантажується API зайвими запитами.

Отримання підписаного документа:

GET /GetMessage?boxId={boxId}&messageId={msgId}&entityId={entityId}

У відповіді — всі версії документа, підписи кожної сторони, часові штампи. Витягуємо підписану версію та файл підпису (.sig), завантажуємо в Bitrix24 через disk.file.upload, прив'язуємо до угоди.

Відмова від підпису. Контрагент може запросити уточнення або відхилити документ. Diadoc передає подію з коментарем. Обробник створює у Bitrix24 задачу менеджеру (tasks.task.add) з текстом відмови й повертає угоду на етап доопрацювання через crm.deal.update.

Маршрути підписання з кількома учасниками

Реальний документообіг — це не одна підпис. Типові сценарії:

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

Паралельне підписання: акт звірки підписують обидві сторони незалежно.

Підписання з внутрішнім узгодженням: перед підписом керівником документ візує юрист і фінансовий директор. Візування — ПНП, фінальна підпис — КП.

В API сервісів маршрут описується набором кроків з учасниками, типом дії й порядком:

{
  "document_id": "doc-456",
  "workflow": [
    {"step": 1, "action": "approve", "participants": ["[email protected]"], "type": "sequential"},
    {"step": 2, "action": "sign", "participants": ["[email protected]"], "type": "sequential"},
    {"step": 3, "action": "sign", "participants": ["[email protected]"], "type": "sequential"}
  ]
}

Що зберігається у Bitrix24 після підписання

Після завершення циклу в CRM повинні опинитися:

• Оригінал документа (PDF)
• Файл відокремленої підпису (.sig) — CAdES або XAdES
• Протокол підписання — хто, коли, яким сертифікатом

Файли завантажуються на Bitrix24.Диск у структуру Підписані документи / [Рік] / [Місяць] / [Номер угоди]. У користувальницьких полях угоди фіксуються дата підписання, номер документа у системі ЕДО, статус.

Сповіщення і автоматизація воронки

Кожна зміна статусу документа в сервісі ЕП транслюється у Bitrix24:

• Сповіщення в чат (im.notify.system.add) — відповідальному менеджеру
• Перевід етапу угоди (crm.deal.update) — автоматично при підписанні обома сторонами
• Коментар у таймлайні (crm.timeline.comment.add) — запис з деталями події
• Задача при відмові (tasks.task.add) — менеджеру на доопрацювання документа

Менеджер не стежить за статусами вручну — система сама сповіщає й рухає угоду по воронці.

Етапи впровадження

Хмарний електронний підпис через зовнішній сервіс усуває залежність від конкретного комп'ютера. Менеджер відправляє документ з карточки угоди, контрагент підписує у інтерфейсі оператора ЕДО, підписана версія автоматично повертається в CRM. Без токенів на кожному робочому місці, без сканера, без очікування кур'єра.