Интеграция Битрикс24 с сервисами электронной подписи

Интеграция Битрикс24 с сервисами электронной подписи

Устанавливать КриптоПро CSP на каждый ноутбук в компании, раздавать токены, ловить баги Browser plug-in после очередного обновления Chrome — не единственный путь. Облачные сервисы электронной подписи снимают привязку к рабочему месту и позволяют выстроить маршруты подписания с несколькими участниками, включая контрагентов.

Какой сервис для какой задачи

Для обмена формализованными документами (УПД, счета-фактуры) с российскими контрагентами — Диадок или СБИС. Для внутреннего подписания без токенов — КриптоПро DSS. Для международных контрактов — DocuSign.

Архитектура интеграции: как это работает изнутри

Общая схема одинакова для всех сервисов, различается только API:

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

Связующее звено — серверный обработчик (webhook-приёмник). В простом варианте — PHP-скрипт на хостинге. Для надёжной работы при высокой нагрузке — очередь задач через Redis или RabbitMQ с гарантированной доставкой и ретраями при ошибках.

Интеграция с Контур.Диадок: полный цикл

Диадок — крупнейший оператор ЭДО в России, и именно с ним чаще всего связывают Битрикс24. 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. Получить файл из Битрикс24: crm.documentgenerator.document.get
2. Определить ящик организации: GET /GetMyOrganizations
3. Найти контрагента в Диадоке: GET /GetCounteragent?myOrgId={id}&counteragentOrgId={id}
4. Для формализованных документов (УПД, акт, счёт-фактура) — POST /GenerateTitleXml, Диадок требует XML в формате ФНС
5. Отправить: POST /PostMessage с вложенным документом и типом

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

Отслеживание статуса. Диадок поддерживает два механизма:

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

На практике webhooks Диадока могут задерживаться на минуты при пиковых нагрузках. Надёжная схема: webhook как триггер немедленной проверки, polling каждые 5 минут как страховка. Так не теряются события и не нагружается API лишними запросами.

Получение подписанного документа:

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

В ответе — все версии документа, подписи каждой стороны, штампы времени. Извлекаем подписанную версию и файл подписи (.sig), загружаем в Битрикс24 через disk.file.upload, привязываем к сделке.

Отказ от подписи. Контрагент может запросить уточнение или отклонить документ. Диадок передаёт событие с комментарием. Обработчик создаёт в Битрикс24 задачу менеджеру (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"}
  ]
}

Что хранится в Битрикс24 после подписания

После завершения цикла в CRM должны оказаться:

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

Файлы загружаются на Битрикс24.Диск в структуру Подписанные документы / [Год] / [Месяц] / [Номер сделки]. В пользовательских полях сделки фиксируются дата подписания, номер документа в системе ЭДО, статус.

Уведомления и автоматизация воронки

Каждое изменение статуса документа в сервисе ЭП транслируется в Битрикс24:

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

Менеджер не следит за статусами вручную — система сама уведомляет и двигает сделку по воронке.

Этапы внедрения

Облачная электронная подпись через внешний сервис убирает зависимость от конкретного компьютера. Менеджер отправляет документ из карточки сделки, контрагент подписывает в интерфейсе оператора ЭДО, подписанная версия автоматически возвращается в CRM. Без токенов на каждом рабочем месте, без сканера, без ожидания курьера.