Отправка документов на подпись из 1С: REST API и внешняя обработка

Если перед вами стоит задача отправить документ на подпись из 1С без выгрузки файлов вручную и пересылки по почте, у Cert4U есть два технических пути: готовая внешняя обработка и прямые вызовы REST API. Оба закрывают один и тот же сценарий — документ из конфигурации уходит контрагенту на подписание по ссылке, а статус возвращается обратно в учётную систему. Эта статья — про глубину: как устроено API подписания 1С, какие методы api_1c_* доступны, как работает авторизация, идемпотентность, песочница и вебхуки статуса. Если вам нужен общий обзор и пошаговая настройка, смотрите полную инструкцию по интеграции с 1С — здесь мы намеренно уходим на уровень разработчика и интегратора.

Два пути интеграции: внешняя обработка или прямой REST API

Выбор пути зависит от того, кто и как будет сопровождать интеграцию. Оба варианта используют одну и ту же серверную логику Cert4U, различаются только точкой, где живёт код.

Путь 1. Готовая внешняя обработка

Внешняя обработка (.epf) — это самостоятельный файл, который подключается к типовой или доработанной конфигурации без изменения её кода. Внутри — модуль формы и модуль объекта на встроенном языке 1С (.bsl), которые уже реализуют вызовы к API Cert4U: выбор документа, отправку на подпись, получение статуса и загрузку подписанного комплекта. Такой коннектор 1С электронная подпись подходит там, где не хочется писать интеграционный код с нуля: вы получаете рабочую форму, привязываете её к нужным объектам и настраиваете реквизиты доступа.

Отдельно стоит отметить формирование CAdES в 1С. Обработка умеет создавать подпись формата CAdES-BES прямо на стороне 1С через КриптоПро — когда у оператора установлен сертификат и криптопровайдер, подпись формируется в рамках сеанса 1С, а не только на стороне контрагента. Это полезно для внутреннего заверения документов и для сценариев, где отправитель тоже ставит квалифицированную подпись.

Путь 2. Прямые вызовы REST API

Если у вас своя конфигурация, свой слой интеграций или вы предпочитаете держать логику под контролем, используйте интеграцию 1С REST API подпись напрямую. Все методы — это HTTP-вызовы с JSON-телом; из 1С они выполняются через HTTPСоединение и HTTPЗапрос. Такой подход даёт полный контроль над обработкой ошибок, повторными попытками и логированием, а также позволяет встроить отправку документа на подпись через API 1С в любой бизнес-процесс — от проведения документа до регламентного задания.

Практическое правило: внешняя обработка — быстрее к запуску, прямой REST API — гибче в сопровождении. Ничто не мешает начать с обработки, а позже перейти на собственные вызовы, потому что за ними стоит один и тот же набор методов.

Методы API: группа api_1c_*

API для 1С сгруппировано в набор методов с префиксом api_1c_* — их около девятнадцати. Ниже — назначение основных групп, чтобы вы понимали покрытие сценария от загрузки файла до отзыва подписи.

Такое разделение позволяет собрать нужный сценарий из независимых шагов. Типичный цикл: загрузить документ → отправить на подпись → получать уведомления через вебхук → по факту подписания скачать ZIP → при необходимости выполнить проверку подписей. Про состав итогового комплекта подробно рассказано в материале про ZIP-архив с протоколом.

Авторизация: X-Api-Key

Все запросы к API аутентифицируются заголовком X-Api-Key. Ключ выдаётся в кабинете Cert4U и однозначно привязан к вашему аккаунту (тенанту), поэтому данные одного клиента не пересекаются с данными другого. В 1С заголовок добавляется к HTTPЗапрос перед отправкой; во внешней обработке он хранится в реквизитах настройки. Ключ — это секрет: не зашивайте его в общедоступный код и не выводите в логи. При компрометации ключ можно перевыпустить в кабинете.

Статусы через вебхуки

Опрашивать статус в цикле неэффективно и создаёт лишнюю нагрузку. Правильный подход — вебхук статуса подписи 1С: вы регистрируете URL, на который Cert4U отправляет уведомление при смене состояния документа (открыт, подписан, отклонён). Управление адресами реализовано тремя операциями — задать (set), получить (get) и удалить (delete), — так что вы можете держать разные точки приёма для разных окружений.

Со стороны 1С приём вебхука делается либо публикацией HTTP-сервиса на веб-сервере (Apache/IIS), либо промежуточным слоем на вашей стороне, который кладёт события в очередь, а 1С забирает их регламентным заданием. Второй вариант удобнее, когда 1С не опубликована наружу: внешний сервис принимает HTTP, а учётная система периодически синхронизируется по расписанию. В обоих случаях по событию «подписан» логично сразу запросить подписанный ZIP и приложить его к документу в базе.

Идемпотентность и повторные попытки

Сетевые вызовы иногда завершаются неопределённостью: запрос ушёл, а ответ потерялся. Чтобы повторная попытка не создала дубль документа, API поддерживает идемпотентность — вы передаёте ключ идемпотентности, и при повторе с тем же ключом сервер вернёт результат исходной операции, а не выполнит её заново. Для 1С это критично: регламентные задания и повторные проведения документа не должны плодить лишние отправки. Стройте логику так, чтобы ключ идемпотентности формировался детерминированно от документа базы (например, из его идентификатора и версии).

Пагинация и объёмные выборки

Методы, возвращающие списки (документы, клиенты), поддерживают пагинацию: данные отдаются страницами, а не одним массивом. Это удобно для регламентной синхронизации — вы обходите страницы, пока они не закончатся, и не рискуете превысить лимиты по объёму ответа. При проектировании выгрузки статусов в 1С закладывайте цикл по страницам, а не разовый запрос «всё сразу».

Песочница для безопасной отладки

Перед боевым запуском интеграцию имеет смысл обкатать в песочнице. Режим песочницы позволяет проверить вызовы api_1c_*, форматы запросов и обработку ответов, не затрагивая реальные документы и не отправляя ничего контрагентам. Это снимает риск «случайно отправить тестовый договор клиенту» на этапе разработки внешней обработки или собственного коннектора.

Быстрый старт для интегратора

Ниже — минимальный маршрут, чтобы увидеть работающую отправку. Это не полная пошаговая настройка (она — в хабе интеграции), а ориентир по последовательности.

• Получите X-Api-Key в кабинете Cert4U и включите режим песочницы.
• Выполните загрузку тестового документа и запомните его идентификатор.
• Вызовите отправку на подпись (ПЭП для быстрой проверки), укажите получателя.
• Зарегистрируйте вебхук (set) на тестовый URL и убедитесь, что приходят события статуса.
• По событию «подписан» скачайте ZIP и выполните verify.
• Проверьте идемпотентность: повторите отправку с тем же ключом и убедитесь, что дубля нет.
• Переключитесь с песочницы на боевой режим.

Полное описание методов, форматов и полей — в документе 1C_API_INSTRUCTION.md, который поставляется с интеграцией. Если ваш типовой сценарий — договоры с частными лицами, посмотрите отдельный разбор сценарий подписания с физлицом из 1С: там учтены нюансы ПЭП и идентификации получателя.

ПЭП и УКЭП: что выбрать для отправки из 1С

Cert4U работает и с простой электронной подписью (ПЭП), и с усиленной квалифицированной подписью (УКЭП) контрагента. Для массовой отправки типовых документов физлицам чаще применяют ПЭП: контрагент подтверждает подписание кодом из SMS или email, без установки криптопровайдера. Юридическая сила ПЭП возникает при соглашении сторон об использовании такой подписи — это прямо предусмотрено частью 2 статьи 6 и статьёй 9 Федерального закона № 63-ФЗ «Об электронной подписи». Для случаев, где требуется квалифицированная подпись, используется УКЭП, которую ставит сам контрагент своим сертификатом. Важно понимать роли: Cert4U не является удостоверяющим центром и не выпускает сертификаты — сервис организует процесс подписания и проверку, работая с ПЭП и с УКЭП клиента.

Частые вопросы

Нужно ли дорабатывать конфигурацию 1С, чтобы отправлять документы на подпись?

Нет, если использовать готовую внешнюю обработку: она подключается как отдельный .epf-файл и не меняет код типовой конфигурации. Если вы идёте через прямой REST API, доработка сводится к добавлению вызовов HTTPЗапрос в нужные места вашей логики.

Можно ли формировать подпись CAdES прямо в 1С?

Да. Внешняя обработка умеет создавать подпись формата CAdES-BES на стороне 1С через КриптоПро, когда у оператора установлен сертификат и криптопровайдер. Это применимо для внутреннего заверения и сценариев, где отправитель тоже подписывает документ.

Как получать статусы, не опрашивая API постоянно?

Используйте вебхуки: зарегистрируйте URL методом set, и Cert4U сам пришлёт уведомление при смене статуса. Приём можно организовать через HTTP-сервис 1С или промежуточный слой с регламентной синхронизацией.

Готовы попробовать на практике? Подключите интеграцию и оцените отправку из 1С: 10 отправок бесплатно, без карты — этого достаточно, чтобы прогнать полный цикл от загрузки документа до получения подписанного ZIP.

Материал носит справочно-технический характер и не является юридической консультацией. Условия применения ПЭП и УКЭП определяются соглашением сторон и требованиями Федерального закона № 63-ФЗ «Об электронной подписи».