Руководство разработчика модуля КриптоАРМ Документы#

В этом руководстве вы узнаете, как создавать, подписывать и управлять документами в CMS 1С-Битрикс с помощью модуля КриптоАРМ Документы, работать с API, хранить и версионировать документы, использовать дополнительные параметры, интегрировать бизнес-процессы с электронной подписью и взаимодействовать с модулем через PHP и JavaScript.

Содержание:

• Подключение модуля КриптоАРМ Документы
• Функции модуля КриптоАРМ Документы
• Константы модуля КриптоАРМ Документы
• Работа с API модуля КриптоАРМ Документы

⚠️ Важно:

• Функции Подпись и Проверка подписи выполняются через программное обеспечение КриптоАРМ версии 6.2 и выше, установленное на рабочем месте пользователя.
• Для работы с алгоритмами ГОСТ требуется установленный криптопровайдер КриптоПРО CSP.
• Сайт должен работать по защищённому протоколу HTTPS.

Подключение модуля КриптоАРМ Документы#

Подключение модуля#

Для подключения модуля на странице достаточно использовать стандартную функцию подключения модулей в CMS 1С-Битрикс и создать псевдоним для пространства имен.

# Пример подключения модуля
use Trusted\CryptoARM\Docs;
CModule::IncludeModule("trusted.cryptoarmdocscrp");

⚠️ Примечание: Название подключаемого модуля зависит от редакции, которую вы установили.

Существующие редакции модулей ядра:

1. trusted.cryptoarmdocsstart
2. trusted.cryptoarmdocsbusiness
3. trusted.cryptoarmdocscrp

В дальнейшем по тексту будем использовать trusted.cryptoarmdocscrp.

Модуль автоматически подключит все необходимые для работы классы и функции, в том числе и javascript-библиотеку с высокоуровневыми функциями, предназначенными для взаимодействия с пользователем.

Создание псевдонима для пространства имен модуля не обязательно, но рекомендуется, т.к. позволяет использовать сокращенную запись при вызове функций модуля.

Псевдоним позволяет использовать вызовы вида:

Docs\Database::getDocuments();

вместо

Trusted\CryptoARM\Docs\Database::getDocuments();

Получение настроек модуля#

Модуль имеет собственный интерфейс для загрузки документов. При его использовании документы автоматически сохраняются в директории, указанной в настройках модуля. Получить путь до этой директории можно с помощью стандартных средств CMS 1С-Битрикс.

# Пример получения настроек модуля
$DOCUMENTS_DIR = COption::GetOptionString("trusted.cryptoarmdocscrp",
"DOCUMENTS_DIR", "docs");

Эта директория задается относительно корня сайта. По умолчанию модуль использует директорию docs в корне сайта.

Функции модуля КриптоАРМ Документы#

Модуль КриптоАРМ Документы предназначен для хранения и категоризации документов, в том числе организации различных бизнес-процессов, нуждающихся в документообороте и для прикрепления электронной подписи к документам.

Подписание документов осуществляется с помощью стороннего приложения, установленного на компьютере пользователя.

Описание принципа хранения документов в модуле#

В модуле документ представляет собой запись в базе данных, содержащую:

• информацию о текущем состоянии документа;
• сведения о связях с другими версиями документа;
• путь к физическому файлу, сохранённому на сервере.

При каждом подписании создаётся новая запись документа:

• указывается идентификатор исходной («родительской») записи;
• предыдущая запись помечается как имеющая «потомка».

Новая запись считается актуальной версией документа.

Таким образом реализуется механизм версионности: документы образуют последовательную цепочку связанных записей (двусвязную структуру).

Для получения списка актуальных документов система выбирает записи, не имеющие потомков, то есть последние версии в цепочке.

Это позволяет:

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

К каждому документу может быть добавлено неограниченное количество дополнительных параметров.

Параметры:

• хранятся в отдельной таблице базы данных;
• представлены в виде пары «тип» — «значение».

Дополнительные параметры позволяют:

• хранить произвольную сопутствующую информацию;
• связывать документы с бизнес-сущностями;
• реализовывать различные сценарии автоматизации и бизнес-процессы.

Такой подход обеспечивает гибкость модели данных и расширяемость модуля без изменения основной структуры хранения документов.

Создание документа#

Функция создания документа добавляет новую запись в базу данных. Файл документа уже должен присутствовать на сервере и лежать в пределах корня сайта.

# Описание функции создания документа
Docs\Utils::createDocument($path, $properties);
PHP, описание функции создания документа

Пример добавления документа#

Добавление нового документа в базу данных.

# Пример вызова функции создания документа
Docs\Utils::createDocument("/docs/document.doc");

После создания записи о документе в базе данных функция вернет получившийся объект класса Document.

# Пример объекта, который возвращает функция создания документа
Trusted\CryptoARM\Docs\Document Object
    (
    [id: protected] => 459
    [name: protected] => document.doc
    [path: protected] => /docs/ 5 qwe6324 / document.doc
    [type: protected] => 0
    [signType: protected] => 0
    [status: protected] => 0
    [parentId: protected] =>
        [childId: protected] =>
        [originalId: protected] => 459
    [hash: protected] => 518214550347e1d0b9f2ba40d3a4b
    [signatures: protected] =>
        [signers: protected] => 1
    [blockBy: protected] => null
    [blockToken: protected] => null
    [blockTime: protected] => 2020-02 - 18 15 : 28 : 47
    [created: protected] =>
        [requires: public] => Trusted\CryptoARM\Docs\RequireCollection Object
            (
                [item_: protected]=> Array
                (
            )
            )
    [properties: public] => Trusted\CryptoARM\Docs\PropertyCollection Object
        (
            [items_: protected] => Array
            (
        )
        )
    )

• Документу автоматически будет назначен уникальный идентификатор.
• Тип и статус будут равны значениям по умолчанию (см. Типы документов и Статусы документов).
• Документ не будет иметь потомка и сам не будет считаться родителем.
• Список дополнительных параметров документа будет пустым.

Пример добавления документа с дополнительным параметром#

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

Рассмотрим пример привязки документа к определенному пользователю.

# Пример вызова функции создания документа с дополнительным параметром
$props = new Docs\PropertyCollection();
$props->add(new Docs\Property("USER", "254"));
Docs\Utils::createDocument("/docs/document.doc", $props);

После создания записи о документе в базе данных функция вернет получившийся объект класса Document.

# Пример объекта, который возвращает функция создания документа при указании дополнительного параметра
Trusted\CryptoARM\Docs\Document Object
    (
    [id: protected] => 557
    [name: protected] => document.doc
    [path: protected] => /docs/document.doc
    [type: protected] => 0
    [status: protected] => 0
    [signers: protected] =>
        [parentId: protected] =>
        [childId: protected] =>
        [created: protected] =>
        [properties] => Trusted\CryptoARM\Docs\PropertyCollection Object
        (
            [items_: protected] => Array
            (
                [0] => Trusted\CryptoARM\Docs\Property Object
                (
                    [id: protected] => 266
                [documentId: protected] => 557
                [type: protected] => USER
                [value: protected] => 254
                )
            )
        )
    )

• Документу автоматически будет назначен уникальный идентификатор.
• Тип и статус будут равны значениям по умолчанию (см. Типы документов и Статусы документов).
• Документ не будет иметь потомка и сам не будет считаться родителем.
• Список дополнительных параметров документа будет содержать один дополнительный параметр, соответствующий указанным в вызове функции аргументам.

Тип и значение параметра могут быть произвольными строками, но длина типа параметра ограничена 50 символами, а значения - 255 символами.

К документу можно прикрепить любое количество дополнительных параметров.

Дополнительные параметры можно прикреплять к документу после его создания (см. Добавление дополнительных параметров к документу).

Методы класса Document#

Объект класса Document имеет ряд методов упрощающих доступ к его свойствам.

Изменение свойств документа и сохранение изменений#

Иногда возникает необходимость изменить какие-то свойства документа, например, если документы были перенесены в другую директорию. Чтобы изменить путь до документа хранящийся в записи в базе данных, достаточно получить нужный документ и использовать один из его методов чтобы получить значение свойства пути.

# Пример пример получения объекта Document по идентификатору и получения пути к файлу этого документа с помощью метода
$doc = Docs\Database::getDocumentById( 557 );
$doc_path = $doc->getPath();

После того как необходимая информация была получена и изменена, ее нужно поместить обратно в объект Document и сохранить его, чтобы обновить информацию в базе данных.

$doc_path .= "/new/path";

# Пример указания нового пути документа и сохранения изменений в базе данных
$doc->setPath($doc_path);
$doc->save();

Получение всех загруженных документов#

Функция получения всех загруженных документов возвращает все конечные документы в цепочке «родитель-потомок», т.е. документы, не имеющие потомков (см. Описание принципа хранения документов в модуле).

# Пример вызова функции получения всех документов
Docs\Database::getDocuments();

Функция вернет объект класса DocumentCollection, содержащий объекты класса Document.

# Пример объекта, возвращаемого функцией получения всех документов
Trusted\CryptoARM\Docs\DocumentCollection Object (
    [items_:protected] => Array (
        [0] => Trusted\CryptoARM\Docs\DocumentObject Object (
            [id:protected]        => 456
            [name:protected]      => document01.txt
            [path:protected]      => /docs/document01.txt
            [type:protected]      => 0
            [status:protected]    => 0
            [signers:protected]   => 
            [parentId:protected]  => 
            [childId:protected]   => 
            [created:protected]   => 2018-03-14 15:44:34
        )
        [1] => Trusted\CryptoARM\Docs\DocumentObject Object (
            [id:protected]        => 457
            [name:protected]      => document02.txt
            [path:protected]      => /docs/document02.txt
            [type:protected]      => 0
            [status:protected]    => 0
            [signers:protected]   => 
            [parentId:protected]  => 
            [childId:protected]   => 
            [created:protected]   => 2018-03-14 15:44:43
        )
        [2] => Trusted\CryptoARM\Docs\DocumentObject Object (
            [id:protected]        => 460
            [name:protected]      => document03.txt
            [path:protected]      => /docs/document03.txt
            [type:protected]      => 0
            [status:protected]    => 0
            [signers:protected]   => 
            [parentId:protected]  => 
            [childId:protected]   => 
            [created:protected]   => 2018-03-14 16:27:01
        )
    )
)

Обработка документов собранных в объект класса DocumentCollection#

Для преобразования объекта DocumentCollection в массив объектов Document используется метод getList. Это позволяет проходить по коллекциям документов с помощью стандартной конструкции foreach языка PHP.

# Пример преобразования объекта класса DocumentCollection в массив объектов Document.
$doc_array = Docs\Database::getDocuments()->getList();

# Пример массива документов, полученных с помощью метода getList
Array (
    [0] => Trusted\CryptoARM\Docs\Document Object (
        [id:protected]        => 456
        [name:protected]      => document01.txt
        [path:protected]      => /docs/document01.txt
        [type:protected]      => 0
        [status:protected]    => 0
        [signers:protected]   => 
        [parentId:protected]  => 
        [childId:protected]   => 
        [created:protected]   => 2018-03-14 15:44:34
    )
    [1] => Trusted\CryptoARM\Docs\Document Object (
        [id:protected]        => 457
        [name:protected]      => document02.txt
        [path:protected]      => /docs/document02.txt
        [type:protected]      => 0
        [status:protected]    => 0
        [signers:protected]   => 
        [parentId:protected]  => 
        [childId:protected]   => 
        [created:protected]   => 2018-03-14 15:44:43
    )
    [2] => Trusted\CryptoARM\Docs\Document Object (
        [id:protected]        => 460
        [name:protected]      => document03.txt
        [path:protected]      => /docs/document03.txt
        [type:protected]      => 0
        [status:protected]    => 0
        [signers:protected]   => 
        [parentId:protected]  => 
        [childId:protected]   => 
        [created:protected]   => 2018-03-14 16:27:01
    )
)

# Пример обхода коллекции документов с помощью конструкции foreach
$doc_array = Docs\Database::getDocuments()->getList();
foreach ($doc_array as $doc) {
echo $doc->getId();
}

Получение документа по идентификатору#

Уникальный идентификатор документа представляет собой число, однозначно указывающее на запись о документе в базе данных. Имея идентификатор, можно получить полную информацию о документе.

# Описание функции получения документа по идентификатору
Docs\Database::getDocumentById($id);

# Пример получения документа по идентификатору
Docs\Database::getDocumentById( 463 );

# Пример результата получения документа по идентификатору
Trusted\CryptoARM\Docs\Document Object (
    [id:protected]       => 463
    [name:protected]     => document01.txt
    [path:protected]     => /docs/document01.txt
    [type:protected]     => 0
    [status:protected]   => 0
    [signers:protected]  => 
    [parentId:protected] => 
    [childId:protected]  => 
    [created:protected]  => 2018-03-14 16:40:48
)

Получение коллекции документов по имени документа#

Функция получения документа по имени всегда возвращает коллекцию документов (объект DocumentCollection), т.к. в базе данных может одновременно находиться несколько разных документов с одинаковыми именами.

# Описание функции получения коллекции документов по имени документа
Docs\Database::getDocumentsByName($name);

# Пример вызова функции получения коллекции документов по имени документа
Docs\Database::getDocumentsByName("document1.txt");

# Пример коллекции документов, полученных в результате получения документа по имени
Trusted\CryptoARM\Docs\DocumentCollection Object (
    [items_:protected] => Array (
        [0] => Trusted\CryptoARM\Docs\DocumentObject Object (
            [id:protected]        => 463
            [name:protected]      => document01.txt
            [path:protected]      => /docs/92660071fc/document01.txt
            [type:protected]      => 0
            [status:protected]    => 0
            [signers:protected]   => 
            [parentId:protected]  => 
            [childId:protected]   => 
            [created:protected]   => 2018-03-14 16:40:48
        )
        [1] => Trusted\CryptoARM\Docs\DocumentObject Object (
            [id:protected]        => 471
            [name:protected]      => document01.txt
            [path:protected]      => /docs/92ce6aa46f/document01.txt
            [type:protected]      => 0
            [status:protected]    => 0
            [signers:protected]   => 
            [parentId:protected]  => 
            [childId:protected]   => 
            [created:protected]   => 2018-03-14 17:08:38
        )
    )
)

Получение коллекции документов по типу дополнительного параметра#

Функция получения документов по типу дополнительного параметра позволяет получать коллекции документов по любому произвольному типу дополнительному параметра.

# Описание функции получения коллекции документов по типу дополнительного параметра
Docs\Database::getDocumentsByPropertyType($type);

# Пример получений коллекции всех документов с привязкой к пользователю
Docs\Database::getDocumentsByPropertyType("USER");

Функция вернет коллекцию конечных документов, к которым прикреплен заданный тип дополнительного параметра, независимо от его значения. После получения коллекции документов их можно обработать один за другим (см. Обработка документов собранных в объект класса DocumentCollection) и получить полный список их дополнительных параметров с помощью метода getProperties (см. Методы класса Document).

# Пример результата получения коллекции документов по типу дополнительного параметра
Trusted\CryptoARM\Docs\DocumentCollection Object (
    [items_:protected] => Array (
        [0] => Trusted\CryptoARM\Docs\DocumentObject Object (
            [id:protected]        => 42
            [name:protected]      => test01.txt
            [path:protected]      => /docs/5b050696a0371/test01.txt
            [type:protected]      => 0
            [status:protected]    => 0
            [signers:protected]   => 
            [parentId:protected]  => 
            [childId:protected]   => 
            [created:protected]   => 2018-05-23 09:13:42
        )
        [1] => Trusted\CryptoARM\Docs\DocumentObject Object (
            [id:protected]        => 43
            [name:protected]      => test09.txt
            [path:protected]      => /docs/5b0506a7581ce/test09.txt
            [type:protected]      => 0
            [status:protected]    => 0
            [signers:protected]   => 
            [parentId:protected]  => 
            [childId:protected]   => 
            [created:protected]   => 2018-05-23 09:13:59
        )
    )
)

Получение коллекции документов по типу и значению дополнительного параметра#

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

# Описание функции получения коллекции документов по типу и значению дополнительного параметра
Docs\Database::getDocumentsByPropertyTypeAndValue($type, $value);

# Пример получений коллекции всех документов с привязкой к пользователю с ID=47
Docs\Database::getDocumentsByPropertyTypeAndValue("USER", "47");

Функция вернет все конечные документы, к которым прикреплен заданный тип дополнительного параметра с заданным значением. После получения коллекции документов их можно обработать один за другим (см. Обработка документов собранных в объект класса documentcollection)и получить полный список их дополнительных параметров с помощью метода getProperties (см. Методы класса document).

# Пример результата получения коллекции документов по типу и значению дополнительного параметра
Trusted\CryptoARM\Docs\DocumentCollection Object (
    [items_:protected] => Array (
        [0] => Trusted\CryptoARM\Docs\DocumentObject Object (
            [id:protected]        => 42
            [name:protected]      => test01.txt
            [path:protected]      => /docs/5b050696a0371/test01.txt
            [type:protected]      => 0
            [status:protected]    => 0
            [signers:protected]   => 
            [parentId:protected]  => 
            [childId:protected]   => 
            [created:protected]   => 2018-05-23 09:13:42
        )
    )
)

Получение дополнительных параметров документа по идентификатору#

Функция получения дополнительных параметров документа всегда возвращает коллекцию параметров (объект PropertyCollection), т.к. в базе данных может одновременно находиться несколько дополнительных параметров, привязанных к одному документу.

# Описание функции получения дополнительных параметров документа по идентификатору документа
Docs\Database::getPropertiesByDocumentId($documentId, $tableName);

# Пример получений дополнительных параметров документа по идентификатору документа
Docs\Database::getPropertiesByDocumentID( 557 );

# Пример результата получения дополнительных параметров документа
Trusted\CryptoARM\Docs\PropertyCollection Object (
    [items_:protected] => Array (
        [0] => Trusted\CryptoARM\Docs\Property Object (
            [id:protected]         => 266
            [documentId:protected] => 557
            [type:protected]       => USER
            [value:protected]      => 254
        )
    )
)

Обработка дополнительных параметров, собранных в объект класса PropertyCollection#

Для преобразования объекта PropertyCollection в массив объектов Property используется метод getList. Это позволяет проходить по коллекциям дополнительных параметров с помощью стандартной конструкции foreach языка PHP.

# Пример преобразования объекта класса PropertyCollection в массив объектов Property
$doc_props = Docs\Database::getPropertiesByDocumentID( 625 )->getList();

# Пример массива дополнительных параметров, полученных с помощью метода getList
Trusted\CryptoARM\Docs\PropertyCollection Object (
    [items_:protected] => Array (
        => Trusted\CryptoARM\Docs\Property Object (
            [id:protected]         => 516
            [documentId:protected] => 625
            [type:protected]       => ORDER
            [value:protected]      => 1
        )
        => Trusted\CryptoARM\Docs\Property Object (
            [id:protected]         => 517
            [documentId:protected] => 625
            [type:protected]       => ROLES
            [value:protected]      => NONE
        )
    )
)

# Пример обхода коллекции документов с помощью конструкции foreach
$doc_props = Docs\Database::getPropertiesByDocumentID( 625 )->getList();
foreach ($doc_props as $prop) {
   echo $prop->getValue();
}

Методы класса Property#

Объект класса Property имеет ряд методов упрощающих доступ к его свойствам.

Добавление дополнительных параметров к документу#

Некоторым бизнес-процессам для реализации необходимо прикреплять к документу более одного дополнительного параметра. После создания документа к нему можно прикрепить неограниченное количество дополнительных параметров.

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

# Получение документа и его дополнительных параметров
$doc = Docs\Database::getDocumentById( 557 );
$doc_props = $doc->getProperties();

Дополнительные параметры будут доступны в виде объекта класса PropertyCollection.

# Пример результата получения коллекции дополнительных параметров
Trusted\CryptoARM\Docs\PropertyCollection Object (
    [items_:protected] => Array (
        [0] => Trusted\CryptoARM\Docs\Property Object (
            [id:protected]         => 266
            [documentId:protected] => 557
            [type:protected]       => USER
            [value:protected]      => 254
        )
    )
)

Добавим к коллекции дополнительный параметр. Необходимо указать тип и значение параметра.

# Добавление нового дополнительного параметра к коллекции дополнительных параметров документа
$doc_props->add(new Property("NEW PROP", "NEW VALUE"));

Теперь коллекция дополнительных параметров содержит два параметра.

# Пример коллекции дополнительных параметров с двумя параметрами
Trusted\CryptoARM\Docs\PropertyCollection Object (
    [items_:protected] => Array (
        => Trusted\CryptoARM\Docs\Property Object (
            [id:protected]         => 266
            [documentId:protected] => 557
            [type:protected]       => USER
            [value:protected]      => 254
        )
        => Trusted\CryptoARM\Docs\Property Object (
            [id:protected]         => 
            [documentId:protected] => 557
            [type:protected]       => NEW PROP
            [value:protected]      => NEW VALUE
        )
    )
)

Остается только вызвать сохранение документа в базе данных. При этом автоматически будут сохранены все его дополнительные параметры.

$doc->save();

Изменение дополнительного параметра документа и сохранение изменений#

При выполнении бизнес-процесса часто возникает необходимость изменить какие-то дополнительные параметры документа, например, когда пользователь, связанный с документом, оплатил заказ или подписал документ.

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

# Получение документа и его дополнительных параметров
$doc = Docs\Database::getDocumentById( 557 );
$doc_props = $doc->getProperties();

Чтобы получить конкретный дополнительный параметр, надо воспользоваться методом getItemByType класса PropertyCollection.

# Получение конкретного дополнительного параметра документа
$user_prop = $doc_props->getPropByType("USER");

После того, как необходимый дополнительный параметр был получен, его можно изменить и сохранить содержащий его документ, чтобы обновить информацию в базе данных.

# Пример задания нового значения дополнительного параметра и сохранения изменений в базе данных
$user_prop->setValue("732");
$doc->save();

Javascript-функции модуля КриптоАРМ Документы#

Большая часть взаимодействия с пользователем в модуле организована в виде javascript-функций. Такие операции, как подписание документов, проверка подписи, запросы на удаление документов выполняются запуском javascript-функций, которые разработчик может назначить на произвольные элементы интерфейса. Для того чтобы не затронуть другие объявленные функции, все функции модуля собраны в одном объекте trustedCA.

Отправка документов на подпись#

Отправка документа на подпись вызывается запуском javascript-функции. Для этого на компьютере пользователя должна быть установлена и запущена программа КриптоАРМ.

// описание функции отправки документа на подпись
trustedCA.sign(ids, extra, onSuccess, onFailure);

Для отправки документов на подпись достаточно знать их уникальные идентификаторы.

// Пример отправки документов на подпись
trustedCA.sign([545, 546]);

Отправленные файлы появятся в окне запущенной программы КриптоАРМ.

Отправленным на подпись документам устанавливается статус DOC_STATUS_BLOCKED (см Статусы документов). Заблокированный документ нельзя повторно отправить на подпись, пока он вернется с подписью или не будет разблокирован вручную (см. Генерация протокола документа).

Параметр extra является необязательным, и используется для передачи дополнительных свойств, например, когда надо указать роль подписывающего (см. Пример организации бизнес процесса с привязкой к заказу).

Функция отправки документа на подпись после запуска возвращает подробную информацию о результате выполнения. Эта информация может быть использована, чтобы показывать пользователю предупреждения о невозможности отправить некоторые документы на подпись.

// пример значения возвращаемого функцией подписи документа, 
// включающий большое количество предупреждений о невозможности подписать некоторые из документов.
{
    "success": true,
    "message": "Some documents were sent for signing",
    "docsOk": [
        {
            "name": "test02.txt",
            "url": "https://www.bitrix.org",
            "id": 69
        }
    ],
    "docsNotFound": [
        70,
        71
    ],
    "docsFileNotFound": [
        {
            "filename": "test08.txt",
            "id": 72
        }
    ],
    "docsBlocked": [
        {
            "filename": "test09.txt",
            "id": 73
        }
    ]
}

Для вывода интерфейса для подписи документов нужно выбрать необходимые идентификаторы документов и подставить их в вызов javascript-функции.

# Пример вывода интерфейса для подписи документов
$all_docs = Docs\Database::getDocuments();
$all_docs_array = $all_docs->getList();
$all_ids = array();

foreach ($all_docs_array as $doc) {
    $doc_id = $doc->getId();
    $doc_name = $doc->getName();

    // Кнопка для индивидуальной подписи
    echo "<input type='button' 
                 value='" . $doc_id . " - " . $doc_name . "' 
                 onclick='sign([" . $doc_id . "])'>";

    $all_ids[] = $doc_id;
}

// Кнопка для групповой подписи всех документов
echo "<input type='button' 
             value='SIGN ALL' 
             onclick='trustedCA.sign(" . json_encode($all_ids) . ")'>";

Отправка документов на проверку подписи#

Отправка документов на проверку подписи вызывается запуском javascript-функции. Для этого на компьютере пользователя должна быть установлена и запущена программа КриптоАРМ.

// Описание функции отправки документов на проверку подписи
trustedCA.verify(ids);

// Пример отправки документов на проверку подписи
trustedCA.verify([545, 546]);

Отправленные файлы появятся в окне запущенной программы КриптоАРМ.

Кнопка «Подписать» будет неактивна для документов, отправленных на проверку подписи.

Для вывода интерфейса для отправки документов на проверку подписи нужно выбрать необходимые идентификаторы документов и подставить их в вызов javascript-функции.

# Пример вывода интерфейса для отправки документов на проверку подписи
$all_docs = Docs\Database::getDocuments();
$all_docs_array = $all_docs->getList();
$all_ids = array();

foreach ($all_docs_array as $doc) {
    $doc_id = $doc->getId();
    $doc_name = $doc->getName();

    // Кнопка проверки для отдельного документа
    echo "<input type='button' 
                 value='" . $doc_id . " - " . $doc_name . "' 
                 onclick='verify([" . $doc_id . "])'>";

    $all_ids[] = $doc_id;
}

// Кнопка проверки всех документов сразу
echo "<input type='button' 
             value='VERIFY ALL' 
             onclick='trustedCA.verify(" . json_encode($all_ids) . ")'>";

Снятие блокировки документа#

Если документ по какой-то причине не удалось подписать (например из-за ошибки в программе КриптоАРМ), то блокировку файла можно снять самостоятельно.

// Описание функции снятия блокировки документов
trustedCA.unblock(ids);

Для снятия блокировки документов достаточно знать их уникальные идентификаторы.

// Пример вызова функции снятия блокировки документов
trustedCA.unblock([545, 546]);

Для вывода на экран интерфейса для снятия блокировки документов нужно выбрать необходимые идентификаторы документов и подставить их в вызов javascript-функции.

# Пример вывода интерфейса для снятия блокировки документов
$all_docs = Docs\Database::getDocuments();
$all_docs_array = $all_docs->getList();
$all_ids = array();

if (empty($all_docs_array)) {
    echo "Нет заблокированных документов.";
} else {
    foreach ($all_docs_array as $doc) {
        $doc_id = $doc->getId();
        $doc_name = $doc->getName();

        // Кнопка разблокировки для конкретного документа
        echo "<input type='button' 
                     value='" . $doc_id . " - " . $doc_name . "' 
                     onclick='unblock([" . $doc_id . "])'>";

        $all_ids[] = $doc_id;
    }

    // Кнопка для массовой разблокировки
    echo "<input type='button' 
                 value='UNBLOCK ALL' 
                 onclick='trustedCA.unblock(" . json_encode($all_ids) . ")'>";
}

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

Протокол документа содержит подробную информацию о документе (включая информацию о подписи документа) в пригодном для печати виде. Запрос на генерацию протокола документа выполняется вызовом javascript-функции.

// Описание функции генерации протокола документа
trustedCA.protocol(id);

Для генерации протокола достаточно знать идентификатор документа.

// Пример вызова функции генерации протокола документа
trustedCA.protocol(545);

Если функция генерации протокола завершится успешно, браузер пользователя начнет скачивание pdf-документа.

Функция «Поделиться документом»#

Некоторые интерфейсы модуля показывают только личные документы текущего пользователя, т.е. такие, у которых установлен дополнительный параметр USER. Пользователи могут поделиться своими личными документами с другими пользователями Битрикс при помощи вызова функции share.

// Описание функции «поделиться документом»
trustedCA.share(ids, email, level);

Предусмотрено два уровня доступа - SHARE_READ и SHARE_SIGN. Первый уровень просто дает другому пользователю просматривать документ, второй позволяет ему отправлять документ на подпись.

// Пример вызова функции «поделиться документом»
trustedCA.share([12], "mail@example.com", "SHARE_SIGN");

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

// Пример вызова функции, запрашивающей у пользователя адрес электронной почты
trustedCA.promptAndShare(ids, level);

Функция отправки документа по почте#

Функция позволяет отправить документ на произвольный адрес электронной почты.

// Описание функции отправки документа по почте
trustedCA.sendEmail(ids, event, eventFields, templateId);

Модуль автоматически устанавливает три почтовых события и шаблона (с префиксом TR_CA_DOCS ).

// Пример вызова функции отправки документа по почте
let fields = {};
fields.EMAIL = "mail@example.com";
trustedCA.sendEmail([12], "TR_CA_DOCS_MAIL_SHARE", fields, 160);

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

// Пример вызова функции, запрашивающей у пользователя адрес электронной почты
trustedCA.promptAndSendEmail(ids, event, eventFields, templateId);

Удаление документа#

Запрос на удаление документа осуществляется вызовом javascript-функции. При удалении документа удаляется запись о документе в базе данных и файл документа на диске. Если документ имеет подпись, будут удалены и оригинальный файл и подписанный.

// Описание функции удаления документа
trustedCA.remove(ids, force, onSuccess, onFailure);

Для установки блокировки документов достаточно знать их уникальные идентификаторы.

// Пример вызова функции удаления документа
remove([561, 562]);

На экран будет выведен запрос на подтверждение удаления.

Документы будут удалены, если пользователь выберет «OK».

Для вывода на экран интерфейса для снятия блокировки документов нужно выбрать необходимые идентификаторы документов и подставить их в вызов javascript-функции.

# Пример вывода интерфейса для удаления документов
$all_docs = Docs\Database::getDocuments();
$all_docs_array = $all_docs->getList();
$all_ids = array();

foreach ($all_docs_array as $doc) {
    $doc_id   = $doc->getId();
    $doc_name = $doc->getName();

    // Кнопка удаления конкретного документа
    echo "<input type='button' 
                 value='" . $doc_id . " - " . $doc_name . "' 
                 onclick='trustedCA.remove([" . $doc_id . "])'>";

    $all_ids[] = $doc_id;
}

// Кнопка для массового удаления всех найденных документов
echo "<input type='button' 
             value='REMOVE ALL' 
             onclick='remove(" . json_encode($all_ids) . ")'>";

Пример организации бизнес-процесса с привязкой к заказу#

В модуле встроен один пример реализации бизнес-процесса — привязка документа к заказу в интернет-магазине CMS 1С-Битрикс и последовательная подпись документа клиентом и продавцом. Чтобы привязать документ к заказу, пользователь загружает документ, указывая три дополнительных параметра. Первый параметр типа ORDER содержит значение, содержащее номер заказа. Второй параметр типа ROLES содержит информацию о наличии подписи клиента и продавца. Третий параметр типа USER привязывает документ к пользователю, оформившему данный заказ.

# Пример вызова функции создания документа с привязкой к заказу в магазине CMS 1С-Битрикс
$props = new Docs\PropertyCollection();
$props->add(new Docs\Property("ORDER", "54"));
$props->add(new Docs\Property("ROLES", "NONE"));
$props->add(new Docs\Property("USER", "42"));
Docs\Utils::createDocument("/docs/document.doc", $props);

При подписании продавцом значение параметра ROLES устанавливается как SELLER, при подписании клиентом — CLIENT. Когда оба участника процесса подписали документ, у него устанавливается значение BOTH. Для того чтобы отличить подпись клиента от подписи продавца, используется аргумент extra функции sign.

// Пример отправки документов на подпись от лица продавца
sign([545, 546, 547], { role: "SELLER" });

# Пример вывода интерфейса отправки документов на подпись от лица клиента
$all_docs = Docs\Database::getDocuments();
$all_docs_array = $all_docs->getList();
$all_ids = array();

foreach ($all_docs_array as $doc) {
    $doc_id   = $doc->getId();
    $doc_name = $doc->getName();

    // Кнопка подписи для отдельного документа с ролью CLIENT
    echo "<input type='button' 
                 value='" . $doc_id . " - " . $doc_name . "' 
                 onclick='sign([" . $doc_id . "], {\"role\": \"CLIENT\"})'>";

    $all_ids[] = $doc_id;
}

// Кнопка массовой подписи всех документов с ролью CLIENT
echo "<input type='button' 
             value='SIGN ALL AS CLIENT' 
             onclick='trustedCA.sign(" . json_encode($all_ids) . ", {\"role\": \"CLIENT\"})'>";

Константы модуля КриптоАРМ Документы#

Таблицы в базе данных#

Типы документов#

Статусы документов#

Работа с API модуля КриптоАРМ Документы#

В модуле начиная с версии 2.1.1 есть возможность работать с API напрямую. Все контроллеры находятся по адресу: https://адрес_сайта/bitrix/components/trusted/api/.

Авторизация на контроллерах происходит посредством логина и пароля c системы CMS Битрикс или посредством токена с сервиса id.trusted.plus. Подробное описание находится на swagger. Все параметры можно передавать через POST (желательнее всего) или же GET запрос.

Существуют несколько контроллеров, которые позволяют:

1. Получить список ID документов к которым пользователь имеет доступ.
2. Получить информацию о документах.
3. Получить ссылки на скачку документов.
4. Удалить документы.
5. Отправить документы на почту.
6. Поделиться документом.
7. Отправить запрос на подпись.
8. Добавить новый документ в систему.
9. Отказаться от доступа к документу.
10. Разблокировать документ отправленный на подпись.
11. Отправить на подпись документ.
12. Загрузить подписанный файл в систему.

Авторизация на контроллерах#

Авторизацию происходит при помощи параметров передаваемых в POST запросе. В случае, если данные подходят, то произойдет авторизация под данным пользователем на одну операцию. Оба способа являются равноправными. Далее будут приведены примеры с token-авторизацией. Авторизация является важным звеном каждого контроллера. Существуют два способа авторизации:

1. Авторизация при помощи логина и пароля с CMS Битрикс.

   Константа	Значение	Описание
   grandType	password	Тип авторизации. В данном примере авторизация идет по логину и паролю.
   login	admin	Логин пользователя в системе CMS Битрикс.
   password	qwerty	Пароль пользователя в системе CMS Битрикс.

2. Авторизация при помощи токена с сервиса https://id.trusted.plus

   Константа	Значение	Описание
   grandType	token	Тип авторизации. В данном примере авторизация идет по токену.
   token	2f1df24b-3b28-48d4-92c7-6a6150e4a11d	Токен пользователя полученного с сервиса id.trusted.plus.

Получение списка ID документов#

Контроллер позволяет получить список ID документов, доступных данному пользователю. Контроллер находится по адресу: https://адрес_сайта/bitrix/components/trusted/api/getList.php. Ответом данного контроллера будет JSON содержащий: код ответа, сообщение

Ответ вида:

{
    "code": 200,
    "message": "ok",
    "data": [
        "2,3,4"
    ]
}

Получение информации о документах#

Получение информации о документах по их ID, в случае, если пользователь имеет доступ к документу. Контроллер находится по адресу: https://адрес_сайта/bitrix/components/trusted/api/getDocs.php.

Ответ вида:

{
    "code": 200,
    "message": "ok",
    "data": [
        {
            "id": 1,
            "code": 900,
            "message": "ok",
            "name": "Какой-то документ.doc",
            "type": 912,
            "status": 921,
            "hash": "60d5d24dadc97596430e96c538273cd0",
            "access": 932,
            "date": "2019-12-12 11:58:30",
            "require": 940,
            "owner": "Женя Спицин"
        }
    ]
}

Получение ссылки на скачивание документов#

Получение ссылки на скачивание документов по их ID в случае, если пользователь имеет доступ к документу. Контроллер находится по адресу: https://адрес_сайта/bitrix/components/trusted/api/downloadDocs.php.

Ответ вида:

{
    "code": 200,
    "message": "ok",
    "data": [
        {
            "id": 1,
            "code": 900,
            "message": "ok",
            "url": "https://localhost/docs/5df8d907c91a0/61Ywypnuw9Y.jpg"
        }
    ]
}

Удаление документов#

Удаление документов по их ID в случае, если пользователь имеет доступ к документу. Контроллер находится по адресу: https://адрес_сайта/bitrix/components/trusted/api/removeDocs.php.

Ответ вида:

{
    "code": 200,
    "message": "ok",
    "data": [
        {
            "id": 5,
            "code": 901,
            "message": "Нет прав"
        }
    ]
}

Отправление документа на почту#

Отправление документов по их ID на почту. Почтовый шаблон настраивается на сайте. Отправка документов будет производиться от лица сайта, но с пометкой от какого пользователя, в случае, если стандартный почтовый шаблон не был изменен. Контроллер находится по адресу: https://адрес_сайта/bitrix/components/trusted/api/sendDocs.php.

Ответ вида:

{
    "code": 200,
    "message": "ok",
    "data": [
        1
    ]
}

Предоставление доступа к документу#

Предоставление доступа к документам по их ID пользователю с данным email адресом. Email адрес должен быть зарегистрированного пользователя в CMS Битрикс вашего сайта, в противном случае вы получите соответствующий ответ. При получении доступа к файлу, пользователь получит email письмо с информации, что получен доступ к файлу. Контроллер находится по адресу: https://адрес_сайта/bitrix/components/trusted/api/shareDocs.php.

Ответ вида:

{
    "code": 200,
    "message": "ok",
    "data": [
        {
            "id": 1,
            "success": true
        }
    ]
}

Отправить документ на подпись#

Отправление запроса на подпись документов по их ID пользователю с указанным email. Email адрес должен быть зарегистрированного пользователя в CMS Битрикс вашего сайта. В противном случае вы получите соответствующий ответ. При получения запроса на подпись, пользователь получит email письмо с информацией, что вы ждете подпись на этом документе, а также поменяется статус документа у пользователя в компоненте “Документы пользователя” на “Требуется подпись”. Контроллер находится по адресу: https://адрес_сайта/bitrix/components/trusted/api/requireToSign.php.

Ответ вида:

{
    "code": 200,
    "message": "ok",
    "data": [
        {
            "id": 1,
            "success": true
        }
    ]
}

Загрузить новый документ#

Данный контроллер позволяет загрузить новый документ. В случае успешной загрузки контроллер вернет вам ID документа. При загрузке, документ привязывается к пользователю которым вы авторизовываетесь. Контроллер находится по адресу: https://адрес_сайта/bitrix/components/trusted/api/addDoc.php.

⚠️ Примечание: На сервере существуют ограничения по максимально допустимому размеру файла. В случае, если файл слишком большой - он не загрузится.

Ответ вида:

{
    "code": 200,
    "message": "ok",
    "data": {
        "id": 23,
        "name": "Какой-то документ.docx"
    }
}

Отказаться от доступа к документу#

Данный контроллер позволяет отказаться от документа, в случае, если ранее к этому документу получили доступ от другого лица. Если вы владелец или у вас нет доступа, то выводятся соответствующие ответы. Контроллер находится по адресу: https://адрес_сайта/bitrix/components/trusted/api/addDoc.php.

Ответ вида:

{
    "code": 200,
    "message": "ok",
    "data": [
        {
            "code": 901,
            "message": "Нет прав"
        }
    ]
}

Разблокировать документы#

Разблокировка документа, если он был заблокирован(отправлен на подпись) и нужно получить доступ для подписывания. Контроллер находится по адресу: https://адрес_сайта/bitrix/components/trusted/api/addDoc.php.

Ответ вида:

{
    "code": 200,
    "message": "ok",
    "data": [
        {
            "code": 901,
            "message": "Нет прав"
        }
    ]
}

Подписать документы#

Позволяет отправить документ на подпись, при этом возвращается информация для подписи документа, а также документ блокируется с целью невозможности каких либо изменений в период подписи. Документ можно разблокировать с помощью интерфейса на сайте, а также через функционал Разблокировать документы. Контроллер находится по адресу: https://адрес_сайта/bitrix/components/trusted/api/addDoc.php..

Ответ вида:

{
    "code": 200,
    "message": "ok",
    "data": [
        {
            "id": 1,
            "code": 900,
            "message": "Все хорошо",
            "name": "КакойтоДокумент.docs",
            "hash": "60d5d24dadc97596430e96c538273cd0",
            "token": "239c5b9f-dc04-42ac-89f7-b716d3965610",
            "license": "string",
            "url": "https://localhost/docs/5df8d907c91a0/КакойтоДокумент.docs"
        }
    ]
}

Загрузить подписанный документ#

Данный контроллер позволяет загрузить подписанный документ, который был получен при помощи контроллера Подписать документы. Токен подписи и ID документа, который подписывают, должны обязательно совпадать, иначе подпись не произойдет и вернется соответствующий ответ. Контроллер находится по адресу: https://адрес_сайта/bitrix/components/trusted/api/addDoc.php.

Ответ вида:

{
    "code": 200,
    "message": "ok",
    "data": [
        {
            "id": 1,
            "code": 900,
            "message": "Все хорошо"
        }
    ]
}

Описание кодов ответов#

Смотрите также#

• Установка и настройка КриптоАРМ Документы
• Руководство администратора модуля КриптоАРМ Документы
• Руководство пользователя модуля КриптоАРМ Документы