Документация API и интеграции

Этот раздел нужен администраторам и интеграторам, которые используют историю не только через стандартные страницы модуля. Для обычной работы контент-менеджера API не требуется.

В модуле есть встроенная техническая страница «Документация API». Ниже приведено пользовательское описание возможностей без подробного кода.

[Скриншот 1: встроенная страница «Документация API»]

Какие задачи можно автоматизировать

• получить историю конкретного объекта;
• получить данные одной версии;
• сравнить две версии;
• создать ручную версию с комментарием;
• восстановить объект до выбранной версии;
• получить статистику истории;
• удалить набор версий программно.

PHP-интерфейс

Основные операции доступны через класс VersionControl. Он используется внутри 1С-Битрикс, когда другому модулю или пользовательскому скрипту нужно сохранить ручную версию, получить историю, сравнить версии или выполнить восстановление.

REST-интерфейс

Модуль регистрирует REST-методы в стандартном REST-механизме 1С-Битрикс. Доступны получение истории/версии, сравнение, создание ручной версии, восстановление, статистика и массовое удаление.

Права проверяются на стороне модуля. Операции чтения и изменения требуют соответствующего доступа, поэтому интеграцию следует выполнять от пользователя или приложения с нужными правами.

[Скриншот 2: список REST-методов во встроенной справке]

Ручные версии

Интеграция может создать снимок с действием MANUAL и собственным комментарием. Такой подход удобен перед внешней синхронизацией или массовой операцией: сначала сохранить контрольную точку, затем менять данные.

События после создания и восстановления

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

Внешние уведомления и расширенные интеграции

В поставке есть служебные классы для webhooks, уведомлений, Highload-блоков, форм и workflow. В стандартной странице настроек версии 0.9.802 эти возможности не имеют отдельного пользовательского интерфейса. Поэтому их следует считать основой для программной интеграции, а не готовой функцией, которую можно включить флажком.

Что проверять перед интеграцией

1. Проверьте права пользователя интеграции.
2. Убедитесь, что тип сущности и инфоблок не исключены, если рассчитываете на автоматические версии.
3. Сделайте тестовую ручную версию.
4. Проверьте её в общем журнале.
5. Проверьте сравнение и восстановление на тестовом объекте.
6. Только после этого подключайте массовые операции.

[Скриншот 3: ручная версия MANUAL в общем журнале]

Важно про опцию «Не создавать версии при импорте/API»

В версии 0.9.802 настройка отображается в форме, но стандартные обработчики изменений её не используют. Если интеграция обновляет элементы через обычные события инфоблока, автоматическая история может продолжить создаваться. Для массовых интеграций сначала проверьте поведение на тесте.

Для конечного пользователя

Если вы не разрабатываете собственную интеграцию, этот раздел можно пропустить. Все основные операции — история, поиск, сравнение, восстановление, экспорт и импорт — доступны через административный интерфейс.

Ручная контрольная точка перед интеграцией

Хороший сценарий для разработчика — создать MANUAL-версию с понятным комментарием непосредственно перед пакетным изменением. Тогда администратор видит в журнале границу операции и может быстро найти состояние «до». Само массовое обновление при этом может дополнительно создавать автоматические версии, если обработчики включены.

Не путайте REST-модуль и публичный URL

REST-методы регистрируются внутри стандартного REST-механизма 1С-Битрикс. В модуле нет отдельной публичной формы с API-ключом, которую нужно включать в настройках. Порядок авторизации определяется конфигурацией REST на вашем портале/сайте.

Массовое удаление через API

Это административная операция. Перед программным удалением большого набора версий сделайте экспорт или протестируйте фильтр на чтение. Удалённая история не восстанавливается автоматически.