Коллеги, мы часто сталкиваемся с необходимостью автоматизации получения статусов документов из внешних систем, таких как СБИС++. В штатных конфигурациях 1С обычно предусмотрены полноценные обработки обмена, но иногда требуется лишь выборочная функциональность, например, периодическая проверка статуса конкретного отправленного документа. Роботизация таких операций, включая проверку информации или перенос данных между окнами, реализуется с помощью платформы для создания программных роботов с визуальным конструктором.
В этой статье мы подробно рассмотрим, как можно получить информацию о статусе документов из СБИС++, минуя запуск полной штатной обработки. Мы проанализируем два основных подхода: прямое взаимодействие с REST API СБИС и извлечение необходимой логики из уже существующей обработки обмена 1С со СБИС.
Наиболее гибкий и современный подход к взаимодействию с СБИС++ для получения статусов документов — это прямое использование их REST API. Это позволяет нам точно контролировать, какие данные мы запрашиваем и как их обрабатываем, не прибегая к тяжеловесным механизмам полной обработки. При тестировании и отладке таких интеграционных запросов непосредственно из среды платформы будет полезен инструмент для тестирования REST API.
Разберем по шагам ключевые этапы этого процесса.
Первый и наиболее критически важный шаг — это авторизация в системе СБИС. Без успешной аутентификации мы не сможем получить доступ к каким-либо данным или выполнять запросы. СБИС предоставляет несколько методов авторизации, но наиболее распространенным для программного взаимодействия является использование метода СБИС.Аутентифицировать.
Метод СБИС.Аутентифицировать: Мы отправляем запрос к API, передавая учетные данные (логин и пароль). В ответ на этот запрос СБИС возвращает уникальный идентификатор сессии (токен).
Передача токена: Полученный идентификатор сессии необходимо передавать в заголовке всех последующих API-запросов. Обычно это делается через заголовок X-SBISSessionID или X-SBISAccessToken. Это позволяет СБИС идентифицировать нас как авторизованного пользователя для каждого запроса.
Авторизация приложений: Для более сложных интеграций или специализированных приложений СБИС также предлагает сервисную авторизацию. В этом случае мы используем идентификатор приложения (app_client_id) и специальные ключи (app_secret, secret_key) для получения токена доступа.
Очень важно учитывать ограничения СБИС на количество активных сессий (обычно не более 5 одновременно) и частоту вызовов метода аутентификации (например, не более 300 раз в минуту с одного IP-адреса). Мы должны строить нашу логику таким образом, чтобы повторно использовать полученный токен до истечения его срока действия, а не аутентифицироваться при каждом запросе.
После успешной авторизации мы готовы запрашивать информацию о документах. Для проверки статусов документов, а также других изменений в документообороте, СБИС предоставляет команду СБИС.СписокИзменений.
Этот метод возвращает набор событий, которые отражают все изменения, произошедшие в документообороте. Эти события могут касаться как входящих, так и исходящих документов. Основная идея заключается в том, чтобы регулярно опрашивать этот метод, чтобы получать актуальные данные.
Важный совет: Для эффективной работы с СБИС.СписокИзменений нам следует отслеживать последний обработанный идентификатор события. При каждом следующем запросе мы можем передавать этот идентификатор, чтобы получать только новые изменения, произошедшие с момента последнего запроса. Это значительно снижает объем передаваемых данных и нагрузку на API.
// Пример упрощенного псевдокода для запроса списка изменений
// Предполагаем, что СессияИД уже получен
// ПоследнийОбработанныйИД - идентификатор последнего события, полученного ранее
Функция ПолучитьИзмененияДокументов(СессияИД, ПоследнийОбработанныйИД)
ЗаголовокАвторизации = Новый Соответствие();
ЗаголовокАвторизации.Вставить("X-SBISSessionID", СессияИД);
ПараметрыЗапроса = Новый Соответствие();
ПараметрыЗапроса.Вставить("limit", 100); // Ограничиваем количество событий за один запрос
Если ПоследнийОбработанныйИД <> Неопределено Тогда
ПараметрыЗапроса.Вставить("from_id", ПоследнийОбработанныйИД); // Запрашиваем изменения начиная с этого ID
КонецЕсли;
// ... Далее формируем и отправляем HTTP-запрос к СБИС API
// (адрес метода СБИС.СписокИзменений)
// с заголовками и параметрами
// ... Обрабатываем ответ JSON
// ОтветСБИС = ВыполнитьHTTPЗапрос("https://online.sbis.ru/service/?method=СБИС.СписокИзменений", ЗаголовокАвторизации, ПараметрыЗапроса);
// Извлекаем список событий
// События = ОтветСБИС.changes;
// Возвращаем список событий и новый ПоследнийОбработанныйИД
Возврат События;
КонецФункции;
После получения набора событий из метода СБИС.СписокИзменений, мы можем проанализировать их, чтобы определить текущий статус нужного нам документа. Статус документа обычно указывается в поле Документ.Состояние.Код в структуре ответа API.
СБИС использует определенные коды состояния для обозначения различных этапов обработки документа, таких как утверждение, отклонение, согласование или аннулирование. Рассмотрим некоторые из наиболее распространенных кодов состояний:
0 — Документ находится в стадии редактирования.
3 — Документ был успешно отправлен получателю.
4 — Документ успешно доставлен получателю, и было получено подписанное извещение о получении. Это важный промежуточный статус.
7 — Выполнение документооборота завершено успешно. Это означает, что получатель подписал документы и вернул их отправителю (например, двусторонний акт или договор).
9 — Выполнение документооборота завершено с проблемами. Обычно это означает, что получатель запросил уточнение или отклонил документы, и они не были подписаны.
10 — Документ активно участвует во внутреннем документообороте СБИС, например, находится на этапе согласования внутри компании получателя.
23 — Документ ожидает обработки запроса на подписание. Это может быть ситуация, когда документ отправлен, но еще не подписан или находится в очереди на подписание.
Важно отметить, что если документ состоит из нескольких вложений (например, пакет документов), и каждое вложение имеет свой собственный статус, то общее состояние пакета документов определяется по "наихудшему" событию. Например, если одно вложение было утверждено, а другое — отклонено, то СБИС присвоит всему документу статус "Отклонен", так как это наиболее критичный статус в рамках пакета.
Для запроса статуса конкретного документа через API или для сопоставления полученных статусов с документами в нашей базе 1С, нам необходим уникальный идентификатор документа. Как справедливо было отмечено в обсуждении, этот идентификатор обычно записывается в свойствах документа в 1С при его первоначальной отправке через СБИС.
Мы должны убедиться, что при отправке документа через СБИС мы сохраняем его внешний идентификатор (который возвращается СБИС) в соответствующем реквизите или регистре сведений нашей базы 1С. Это позволит нам в дальнейшем легко найти нужный документ в 1С по его СБИС-идентификатору и обновить его статус.
Альтернативный подход, который также обсуждался на форуме, заключается в использовании уже существующей штатной обработки обмена со СБИС, но не в ее полном виде, а путем извлечения из нее необходимой функциональности. Этот метод может быть предпочтителен, если мы не хотим полностью с нуля реализовывать HTTP-запросы и парсинг JSON, а хотим воспользоваться уже готовой, отлаженной логикой. При необходимости отладки и перехвата таких запросов непосредственно на рабочей базе можно использовать инструмент для мониторинга HTTP-трафика.
Штатная обработка обмена со СБИС (плагин) для 1С содержит весь необходимый код для взаимодействия с API СБИС, включая:
Алгоритмы авторизации: В обработке уже реализованы процедуры получения идентификатора сессии и его сохранения/передачи.
Формирование запросов: Код для формирования HTTP-запросов к различным методам API СБИС (включая, вероятно, и для получения статусов) уже присутствует.
Парсинг ответов: Логика для разбора ответов от СБИС (чаще всего в формате JSON) и извлечения из них данных также реализована.
Нам необходимо "перебрать" эту обработку, то есть тщательно изучить ее код. Наша цель — выделить только те функции и процедуры, которые отвечают за авторизацию и запрос списка изменений/статусов документов. Например, мы ищем фрагменты кода, где вызываются методы СБИС API, такие как СБИС.Аутентифицировать и СБИС.СписокИзменений.
После идентификации этих фрагментов мы можем:
Скопировать код: Выделить нужные процедуры и функции в отдельный модуль, например, в расширение конфигурации или новую внешнюю обработку.
Адаптировать: Убрать лишнюю логику, не относящуюся к нашей задаче (например, отправку новых документов, получение печатных форм), и адаптировать оставшийся код для работы в нашем контексте.
Это позволит нам получить рабочую часть кода для взаимодействия со СБИС без необходимости поддерживать и запускать всю сложную структуру штатной обработки.
После того как мы извлекли и адаптировали код для получения статусов, нам нужно реализовать механизм для их записи в нашу базу 1С. Это включает в себя:
Сопоставление документов: Используя сохраненный идентификатор документа СБИС, мы находим соответствующий документ в нашей базе 1С.
Обновление реквизитов: Обновляем реквизиты документа, такие как "СтатусЭДО", "ДатаПодписания" и т.д., на основе полученных данных из СБИС.
Журналирование: Желательно вести журнал изменений статусов для отслеживания истории документооборота.
Для периодической проверки статусов мы можем создать регламентное задание в 1С. Это задание будет запускаться по расписанию, выполнять наш адаптированный код, получать новые статусы из СБИС и обновлять их в нашей информационной базе.
Пример архитектуры решения:
Создаем расширение конфигурации или новую внешнюю обработку.
В это расширение или обработку помещаем скопированную и адаптированную логику авторизации и получения списка изменений из штатной обработки СБИС.
Реализуем функцию или процедуру, которая будет вызываться регламентным заданием.
Эта функция будет:
Выполнять авторизацию в СБИС.
Запрашивать список изменений, передавая последний обработанный ID.
Итерировать по полученным событиям.
Для каждого события находить соответствующий документ в 1С по его СБИС-идентификатору.
Обновлять статус документа в 1С.
Сохранять максимальный ID события для следующего запуска регламентного задания.
Такой подход позволяет нам получить необходимую функциональность без перегрузки системы избыточными операциями штатной обработки и эффективно автоматизировать процесс отслеживания статусов документов.
Мы выяснили, что оба подхода — как прямое использование API, так и модификация существующей обработки — являются жизнеспособными. Выбор зависит от вашей готовности к детальной работе с API или к анализу и адаптации существующего кода. В любом случае, ключ к успеху — это понимание принципов авторизации, работы с идентификаторами и методов API СБИС для получения информации об изменениях.