Описание области применения API приложений экосистемы ISV

1. Обзор

Настоящий документ предназначен для предоставления разработчикам партнеров экосистемы описания Scope (доменов прав) в системе авторизации приложений eSignGlobal. При интеграции приложения разработчики должны запрашивать соответствующие Scope в соответствии с реальными требованиями бизнес-функций. Каждый Scope включает список OpenAPI, доступных для вызова в рамках данного домена прав. Платформа будет строго контролировать права приложений на выполнение операций с соответствующими ресурсами на основе выданных Scope.

Базовые интерфейсы аутентификации

Перед официальным вызовом интерфейсов экосистемными приложениями необходимо сначала получить учетные данные для вызова через конечную точку авторизации:

Название интерфейса	Путь интерфейса	Описание интерфейса
Получение AccessToken	`POST /esignglobal/v1/oauth2/accessToken`	С помощью appid и appsecret получить access_token для аутентификации, который используется для запросов к API eSignGlobal от имени конкретного пользователя. Срок действия токена составляет 24 часа.

В настоящее время открытые домены прав Scope в экосистеме eSignGlobal включают в основном:

signature: Основные услуги электронной подписи
stamp: Сервис управления печатями
comparisons: Сервис сравнения договоров

2. Подробности о Scope и перечень интерфейсов

2.1 Scope: `signature` (сервис электронной подписи)

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

Модуль 1: Сервис шаблонов

Название интерфейса	Описание интерфейса
Получить сведения об элементах управления шаблона для подписанта	Получить информацию об элементах управления шаблона для указанного подписанта и соответствующие настройки атрибутов
Получить сведения о шаблоне	Получить полную информацию о конкретном шаблоне, включая поля и структуру файла
Заполнение шаблона и генерация файла	Заполнение бизнес-данных на основе заданного шаблона и автоматическое формирование файла в формате PDF
Запрос списка шаблонов	Получение списка доступных шаблонов текущего аккаунта с пагинацией или по заданным условиям фильтрации
Получение сведений о задаче формирования файла	Получить итоговый результат выполнения задачи генерации файла из шаблона по идентификатору асинхронной задачи

Модуль 2: Управление файлами

Название интерфейса	Описание интерфейса
Загрузить файл	Загрузить указанные локальные файлы или файлы бизнес-процесса на платформу для последующего подписания
Получение координат по ключевым словам	Выполнить поиск текста в загруженных документах и вернуть информацию о координатах расположения совпавших ключевых слов
Скачать файл	Скачать определённый завершённый подписанный документ, исходный файл или другой сопутствующий бизнес-файл
Добавить файл для подписания	Привязать ранее успешно загруженные файлы к конкретному подписному конверту или рабочему процессу
Удалить файл для подписания	Удалить из рабочего процесса конверта ошибочно загруженные или временно не требующие подписания файлы
Добавить вложение	Добавить дополнительные пояснительные вложения к конверту или процессу подписания
Удалить вложение	Удалить указанные документы-вложения из конверта или процесса подписания

Модуль 3: Управление участниками

Название интерфейса	Описание интерфейса
Добавить подписанта	Добавить участника подписания, которому требуется выполнить действие по подписанию, в определенный процесс конверта
Удалить подписанта	Удалить отмененного участника подписания из конкретного процесса конверта
Добавить получателя копии	Добавить роль получателя копии, предназначенную только для получения уведомлений о ходе процесса и просмотра окончательно подписанного документа
Удалить получателя копии	Удалить конкретную роль получателя копии

Модуль 4: Управление конвертами

Название интерфейса	Описание интерфейса
Быстрый запуск конверта	Если платформа-интегратор использует этот интерфейс для создания конверта и после завершения подписания система автоматически обрабатывает процесс закрытия, нет необходимости вручную вызывать «Закрытие конверта».
Создание конверта	Предназначено для создания конверта в статусе черновика, поддерживает настройку темы подписания, параметров подписантов и других параметров.
Активация конверта	После подтверждения корректности всех подписываемых документов и подписантов официально передает задачи на подписание в нижестоящую систему.
Закрытие конверта	Ручное закрытие конверта. До закрытия конверта все подписанты должны завершить подписание; после завершения процесса ресурсы не подлежат изменению.
Получение адреса для подписания	Получение персональной короткой ссылки или URL страницы подписания, готового к прямой загрузке, для указанного подписанта.
Получение информации о конверте	Получение общей информации о конверте, связанных файлов, участников и текущего статуса рабочего процесса.
Отмена конверта	Инициатор может самостоятельно отозвать подписной конверт, который еще не был полностью подписан
Напоминание о подписании конверта	При неполном подписании конверта поддерживается отправка напоминаний текущим подписантам, которым необходимо поставить подпись. Интервал между напоминаниями составляет 30 минут
Получение ссылки на страницу предпросмотра подписания	После открытия конверта данный интерфейс позволяет получить ссылку на страницу предпросмотра подписания. В основном используется во внешней платформе для предоставления участникам, не являющимся сторонами конверта, возможности просматривать документы и отслеживать статус подписания
Создание представления отправителя конверта	Создание представления отправителя конверта по его идентификатору. При запуске процесса подписания через это представление информация об инициаторе будет заполнена данными пользователя, извлеченными из токена доступа OAuth

2.2 Scope: `stamp` (Сервис управления печатями)

Данный Scope предназначен специально для авторизации управления корпоративными печатями или личными именными печатями. Подходит для сторонних экосистем, которым требуется только обслуживание единой библиотеки корпоративных печатей (создание, удаление, изменение и поиск печатей), без прямого вмешательства в процесс инициирования подписания

Название API	Описание API
Запрос списка печатей	Использование AppID с соответствующими правами на запрос печатей для получения данных списка ресурсов печатей
Создание печати	Использование авторизованного AppID для создания печати путем передачи строки в кодировке Base64 загруженного изображения (поддерживается формат PNG, размер от 18 мм до 100 мм)
Редактировать штамп	Изменение информации (название, изображение и др.) для уже созданного штампа
Удалить штамп	Полное удаление указанного ресурса штампа, утратившего бизнес-связи

2.3 Scope: `comparisons` (Сервис сравнения контрактов)

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

Название интерфейса	Описание интерфейса
Получение страницы результатов сравнения контрактов	Получение адреса визуальной страницы отображения результатов сравнения различий
Запрос деталей сравнения контрактов	Получение результатов сравнения контракта по бизнес-ID сравнения, включающее количество различий (добавлено, удалено, изменено) и подробное содержание различий (детальная локализация).