REST: подпись документов (Sign)

Модуль «Подпись» (Sign) в Битрикс24 закрывает электронный документооборот с клиентами и сотрудниками. Публичный REST у самого Sign ограничен, поэтому автоматизацию строят вокруг генерации документов, Диска и событий CRM. Разберём, что реально доступно из REST и как собрать рабочий сценарий.

Что такое Sign и где заканчивается REST

«Подпись» (Sign) — продукт Битрикс24 для дистанционного подписания: договоры с клиентами (B2B/B2C) и кадровый ЭДО (КЭДО) с сотрудниками. Пользователь загружает или генерирует документ, расставляет поля подписи, отправляет второй стороне, а платформа фиксирует факт подписания простой электронной подписью с SMS-подтверждением.

Важно понимать границы: у Битрикс24 нет полноценного публичного REST-scope sign для сквозного создания и отправки документа на подпись «одним методом». Поэтому интеграция строится комбинированно — из методов, которые действительно доступны в REST: генератор документов, Диск, CRM-сущности и события.

Права, вебхук и окружение

Для сценариев вокруг подписи потребуется несколько scope сразу: crm, documentgenerator, disk. Проще всего начать с входящего вебхука.

• crm — карточки сделок, смарт-процессов и контактов, к которым привязан документ;
• documentgenerator — генерация PDF/DOCX из шаблона;
• disk — хранение исходников и подписанных версий;
• user и im — уведомления ответственным.

Базовый вызов через вебхук выглядит так:

POST https://portal.bitrix24.ru/rest/1/xxxxxxxxxxxx/documentgenerator.document.add.json

Генерация документа для подписи

Документ на подпись почти всегда рождается из шаблона. Метод documentgenerator.document.add собирает PDF из шаблона и данных CRM-сущности:

documentgenerator.document.add(templateId: 12, entityTypeId: 2, entityId: 145, values: {"ContractNumber":"A-2026-114"}, fields: {...})

В ответе придёт объект document с полями id, pdfUrl, downloadUrl. Именно этот PDF далее становится основой карточки подписания.

Перед генерацией стоит проверить, что шаблон существует и содержит нужные плейсхолдеры: список отдаёт documentgenerator.template.list, а описание полей конкретного шаблона — documentgenerator.template.getFields. Так вы заранее знаете, какие ключи класть в values, и не получите документ с незаполненными полями. Если тот же договор нужно перевыпустить с новыми данными, документ пересобирают повторным вызовом documentgenerator.document.add — предыдущая версия остаётся в истории сущности CRM.

Хранение и передача файлов через Диск

Подписанные и исходные файлы удобно держать в структурированной папке на Диске — так их видят и робот, и человек. Загрузка выполняется через disk.folder.uploadfile:

1. получаем целевую папку: disk.folder.getchildren(id: 55);
2. грузим PDF: disk.folder.uploadfile(id: 55, data: {NAME: "contract.pdf"}, fileContent: ["contract.pdf", "BASE64..."]);
3. получаем публичную ссылку: disk.file.getExternalLink(id: 9012).

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

Автоматизация: события и роботы

Так как отправку на подпись инициирует UI Sign, автоматику вешают на результат. Практичный приём — регистрировать смарт-процесс «Подписание» и слушать его события через REST:

event.bind(event: "ONCRMDYNAMICITEMUPDATE", handler: "https://you.app/hook")

Когда стадия смарт-процесса меняется на «Подписано», ваш обработчик получает FIELDS[ID] и подтягивает документ через crm.item.get. Альтернатива без своего сервера — CRM-робот на входящий вебхук, вызываемый на нужной стадии.

• event.bind / event.unbind — подписка на события;
• crm.item.get — чтение карточки процесса подписания;
• crm.timeline.comment.add — фиксация факта подписи в таймлайне.

Обработчик события должен отвечать быстро и быть идемпотентным: Битрикс24 может повторить доставку, если ваш сервер ответил не за отведённое время или вернул ошибку. Практика — сразу принять запрос, поставить его в очередь и обработать асинхронно, а в CRM записать результат отдельным вызовом. Проверяйте application_token из тела запроса, чтобы отсекать посторонние обращения к вашему вебхуку.

КЭДО: особенности сотрудников

Кадровый ЭДО отличается тем, что вторая сторона — сотрудник портала, а не внешний контакт. Для массовых рассылок документов автоматизацию строят на списке пользователей и уведомлениях:

• user.get — выборка сотрудников подразделения по UF_DEPARTMENT;
• documentgenerator.document.add — персональный приказ/уведомление по шаблону;
• im.notify.system.add — уведомление сотруднику со ссылкой.

Итог

Sign в Битрикс24 — это UI-центричный продукт, но вокруг него собирается полноценная автоматизация: генератор документов создаёт файл, Диск хранит версии, CRM-события и роботы ловят факт подписания, а уведомления держат людей в курсе. Полагаться на «магический» единый REST-метод подписи не стоит — надёжнее сцепить проверенные методы.

Мы в B2Bsite проектируем такие связки под конкретный регламент документооборота: от шаблонов и смарт-процессов до обработчиков событий на вашем сервере. Если нужен предсказуемый и юридически аккуратный ЭДО на Битрикс24 — поможем собрать его без костылей.