API: работа с пакетами документов

`POST` `/api/package` - регистрация пакета документов

Важно! Регистрация пакета документов не будет завершена до тех пор пока для всех документов пакета не будет выполнена POST /api/{id}/data - фиксация значений хешей документа.

Пакет документов - это набор документов для которых можно задавать одинаковые настройки, а так же:

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

В рамках регистрации пакета будет зарегистрирован сам пакет и документы этого пакета, то есть будут зарезервированы идентификатор пакета и идентификаторы документов.

Запрос (Content-Type необходимо установить в application/json):

{
  "title": "package title",
  "description": "package description",
  "emailNotifications": {
    "to": ["user@example.com","other@example.com"],
    "doNotAttachDocuments": false,
    "language": "ru"
  },
  "settings": {
    "private": false,
    "packageAccess": [],
    "packageSettings": [],
    "signWholePackage": false
  },
  "documentsSettings": {},
  "documents": [
    {"title": "some title 1", "description": "some description 1"},
    {"title": "some title 2", "description": "some description 2"},
    {"title": "some title N", "description": "some description N"}
  ]
}

title - название пакета документов;
description - описание пакета документа;
emailNotifications - опциональный параметр, объект настроек для отправки уведомлений по электронной почте о подписании пакета документов с полями:
- to - массив адресов электронной почты;
- doNotAttachDocuments - опциональное поле, позволяет отправлять уведомления без прикрепленных документов, по умолчанию false;
- language - опциональное поле, позволяет задать язык уведомления, поддерживаются строки "ru", "kk", "en" и их комбинации через "/", к примеру "kk/en";
settings - опциональный параметр, объект настроек пакета документов, описание приведено в POST /api/package/{packageId}/settings - изменение настроек пакета документов;
documentsSettings - опциональный параметр, объект настроек документов, эти настройки будут применены к документам пакета, на сам пакет они не влияют, описание приведено в POST /api/{id}/settings - изменение настроек документа;
documents - массив объектов описывающих документы пакета.

Ответ:

{
  "packageId": "xxx",
  "documentsIds": ["id1", "id2", "idN"]
}

packageId - уникальный идентификатор зарегистрированного пакета документов;
documentsIds - массив уникальных идентификаторов зарегистрированных документов в этом пакете.

`GET` `/api/package/{packageId}` - получение данных о зарегистрированном пакете документов

{packageId} - идентификатор пакета документов.

Ответ:

{
  "packageId": "xxx",
  "title": "some title",
  "description": "some description",
  "storedAt": 1568809427182,
  "registrator": {
    "businessId":"BIN012345678901",
    "certificate":"base64_encoded_mtls_certificate"
  },
  "emailNotifications": {
    "to": ["user@example.com","other@example.com"],
    "doNotAttachDocuments": false,
    "language": "ru"
  },
  "signatureEmailNotifications": [
    {
      "signIds": [1, 2, 3],
      "doNotAttachDocuments": false,
      "to": ["user@example.com","otherUser@example.com"],
      "language": "ru"
    },
    {
      "signIds": [4, 5, 6],
      "doNotAttachDocuments": true,
      "to": ["3@example.com","4@example.com"]
    },
  ],
  "settings": {
    "private": false,
    "packageAccess": [],
    "packageSettings": [],
    "signWholePackage": false
  },
  "documentsSettings": {},
  "documentsIds": ["id1", "id2", "idN"]
}

packageId - идентификатор пакета документов;
title - название пакета документов;
description - описание пакета документа;
storedAt - время сохранения пакета (миллисекунд с UNIX Epoch);
registrator - информация об информационной системе зарегистрировавшей пакет документов (БИН и mTLS сертификат в base64);
emailNotifications - информация о том, кому была запрошена отправка уведомлений по электронной почте при регистрации пакета документов;
signatureEmailNotifications - массив объектов, информация о том, кому была запрошена отправка уведомлений по электронной почте при регистрации подписей;
settings - объект настроек пакета документов, описание приведено в POST /api/package/{packageId}/settings - изменение настроек пакета документов;
documentsSettings - объект настроек документов, эти настройки будут применены к документам пакета, на сам пакет они не влияют, описание приведено в POST /api/{id}/settings - изменение настроек документа;
documentsIds - массив идентификаторов документов в этом пакете.

`POST` `/api/package/{packageId}` - добавление подписей к документам пакета

{packageId} - идентификатор пакета документов.

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

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

В том случае, если для пакета установлен signWholePackage, то подписи к документам пакета можно добавлять только через этот API, добавлять подписи под отдельные документы через POST /api/{id} - добавление подписи к документу не получится.

Запрос (Content-Type необходимо установить в application/json):

{
  "signatures": [
    {
      "signType":"cms",
      "signature":"signB641"
    },
    ...
    {
      "signType":"xml",
      "signature":"<xml></xml>"
    }
  ],
  "signatureEmailNotifications": {
    "to": ["user@example.com","other@example.com"],
    "doNotAttachDocuments": false,
    "language": "ru"
  }
}

signatures - массив подписей, структура описана в POST /api/{id} - добавление подписи к документу;
signatureEmailNotifications - опциональный параметр, объект настроек для отправки уведомлений по электронной почте о регистрации новых подписей под документами пакета с полями:
- to - массив адресов электронной почты;
- doNotAttachDocuments - опциональное поле, позволяет отправлять уведомления без прикрепленных документов, по умолчанию false;
- language - опциональное поле, позволяет задать язык уведомления, поддерживаются строки "ru", "kk", "en" и их комбинации через "/", к примеру "kk/en".

Ответ:

{
  "packageId": "xxx",
  "registrationResults": [{}]
}

packageId - идентификатор пакета документов;
registrationResults - массив объектов с результатами регистрации подписей, структура описана в POST /api/{id} - добавление подписи к документу.

`POST` `/api/package/{packageId}/notify` - отправка уведомлений о пакете документов

{packageId} - идентификатор пакета документов.

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

Запрос (Content-Type необходимо установить в application/json):

{
  "emailNotifications": {
    "to": ["user@example.com","other@example.com"],
    "doNotAttachDocuments": false,
    "language": "ru"
  }
}

emailNotifications - параметры отправки email уведомлений:
- to - массив адресов электронной почты;
- doNotAttachDocuments - опциональное поле, позволяет отправлять уведомления без прикрепленных документов, по умолчанию false;
- language - опциональное поле, позволяет задать язык уведомления, поддерживаются строки "ru", "kk", "en" и их комбинации через "/", к примеру "kk/en".

Ответ:

{
  "packageId": "lQsqLBaS4nQAIIMm",
  "emailNotifications": {
    "attached": true,
  }
}

packageId - идентификатор пакета документов;
emailNotifications - результат отправки уведомлений:
- attached - флаг указывающий были ли прикреплены документы к отправленным уведомлениям.

`POST` `/api/package/{packageId}/settings` - изменение настроек пакета документов

{packageId} - идентификатор пакета документов.

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

Все текущие настройки пакета документов будут перезаписаны. В том случае, если в передаваемом новом объекте настроек какая-то настройка отсутствует, будет использовано значение по умолчанию, а не старое значение.

Запрос (Content-Type необходимо установить в application/json):

{
  "private": false,
  "packageAccess": [
    { "iin": "IIN112233445566" },
    { "iin": "IIN665544332211", "bin": "BIN112233445566" },
    { "bin": "BIN112233445566" }
  ],
  "packageSettings": [
    { "iin": "IIN112233445566" },
    { "iin": "IIN665544332211", "bin": "BIN112233445566" },
    { "bin": "BIN112233445566" }
  ],
  "signWholePackage": false
}

private - опциональное поле, определяет ограничен ли доступ к пакету документов (см. Аутентификация и контроль доступа), либо он является общедоступным пакетом документов, по умолчанию false;
packageAccess - опциональное поле, позволяет задавать дополнительные правила предоставления доступа к информации о пакете документов (но не к документам в пакете), подробности про контроль доступа тут;
packageSettings - опциональное поле, позволяет задавать дополнительные правила предоставления доступа к изменению настроек пакета документов (но не изменения настроек документов пакета), подробности про контроль доступа тут;
signWholePackage - блокирует возможность добавлять подписи под документы пакета через POST /api/{id} - добавление подписи к документу, можно добавлять только через POST /api/package/{packageId} - добавление подписей к документам пакета, то есть подписывать можно только все документы пакета одной операцией, по умолчанию false.

Дополнительные правила предоставления доступа к информации о пакете документов (но не к документам в пакете) packageAccess - это объекты со следующей структурой:

{
  "iin": "IIN112233445566",
  "bin": "BIN665544332211"
}

iin - опициональное поле, ИИН пользователя которому необходимо предоставить доступ;
bin - опициональное поле, БИН организации которой необходимо предоставить доступ.

Дополнительные правила предоставления доступа к изменению настроек пакета документов (но не изменения настроек документов пакета) packageSettings - это объекты со следующей структурой:

{
  "iin": "IIN112233445566",
  "bin": "BIN665544332211"
}

iin - опициональное поле, ИИН пользователя которому необходимо предоставить доступ;
bin - опициональное поле, БИН организации которой необходимо предоставить доступ.

Ответ:

{
  "packageId": "lQsqLBaS4nQAIIMm"
}

packageId - идентификатор пакета документов.

`GET` `/api/package/{packageId}/settingsAudit?lastEventId=X` - аудит изменений настроек пакета документов

{packageId} - идентификатор пакета документов;
lastEventId=X - опционально, последний идентификатор записи после которого нужно возвращаться записи.

Возвращает журнал изменений настроек пакета документов.

Ответ:

{
  "packageId": "lQsqLBaS4nQAIIMm",
  "eventsTotal": 3,
  "events": []
}

packageId - идентификатор пакета документов, должен быть идентичен переданному идентификатору;
eventsTotal - количество изменений зарегистрированных в системе;
events - массив объектов описывающих изменения.

Структура объектов описывающих изменения:

{
  "eventId": 1,
  "original": {},
  "modified": {},
  "modifiedBy": "IIN123456789",
  "modifiedByDigest": "XXXXXXXXXXXXXXX",
  "modifiedAt": 1586167317737
}

eventId - идентификатор события;
original - настройки до изменения;
modified - настройки после изменения;
modifiedBy - кем были произведены изменения, ИИН;
modifiedByDigest - хеш mTLS сертификата в том случае, если изменение было выполненой от имени информационной системы;
modifiedAt - момент изменения в миллисекундах с UNIX Epoch.

`POST` `/api/package/{packageId}/egovQr` - регистрация процедуры упрощенного подписания пакета документов через QR или диплинки

{packageId} - идентификатор пакета документов.

Позволяет инициировать подписание через eGov mobile/business всего пакета документов, а так же выполнить регистрацию полученных подписей под данным пакетом.

Важно:* Все документы пакета должны находиться в архиве или временном хранилище, так как они будут отправлены в eGov mobile/business нашим сервисом.

В случае успешного выполнения под каждый документом пакета будет зарегистрирована новая подпись, статус выполнения процедуры можно отслеживать с помощью GET /api/package/{packageId}/egovOperation/{operationId} - получение статуса процедуры подписания пакета документов, отменить процедуру можно с помощью DELETE /api/package/{packageId}/egovOperation/{operationId} - отмена процедуры подписания пакета документов.

Запрос (Content-Type необходимо установить в application/json):

{
  "description": "Анкета и договор на подпись",
  "meta": [
    [
      {
        "name": "Анкета номер",
        "value": "1234"
      }
    ],
    [],
    [
      {
        "name": "Номер договора",
        "value": "1234"
      },
      {
        "name": "Контрагент",
        "value": "ТОО Контрагент"
      }
    ]
  ],
  "signatureEmailNotifications": {
    "to": ["user1@example.com","other1@example.com"],
    "doNotAttachDocuments": false,
    "language": "ru"
  }
}

description - описание регистрируемой процедуры подписания, текст будет отображен в eGov mobile/business;
meta - опциональный массив массивов метаданных подписываемого пакета документов, если поле указано, то количество элементов в нем должно быть равно количеству документов в пакете, в том случае, если для какого-то документа метаданные указывать не нужно, следует указать пустой массив;
signatureEmailNotifications - опциональный параметр, объект настроек для отправки уведомлений по электронной почте о регистрации новых подписей под документами пакета с полями:
- to - массив адресов электронной почты;
- doNotAttachDocuments - опциональное поле, позволяет отправлять уведомления без прикрепленных документов, по умолчанию false;
- language - опциональное поле, позволяет задать язык уведомления, поддерживаются строки "ru", "kk", "en" и их комбинации через "/", к примеру "kk/en".

Ответ:

{
  "operationId": "12345",
  "expireAt": 1668758024082,
  "qrCode": "XXXXX",
  "eGovMobileLaunchLink": "https://...",
  "eGovBusinessLaunchLink": "https://..."
}

operationId - строка, идентификатор зарегистрированной процедуры подписания;
expireAt - момент истечения срока действия процедуры подписания в миллисекундах с UNIX Epoch;
qrCode - строка, закодированное в base64 изображение в формате PNG с закодированным QR кодом для приложения eGov mobile/business;
eGovMobileLaunchLink - диплинк для запуска eGov mobile на том же устройстве;
eGovBusinessLaunchLink - диплинк для запуска eGov Business на том же устройстве.

`GET` `/api/package/{packageId}/egovOperation/{operationId}` - получение статуса процедуры подписания пакета документов

{packageId} - идентификатор пакета документа;
{operationId} - идентификатор процедуры подписания.

Позволяет отслеживать статус процедур подписания зарегистрированных через POST /api/package/{packageId}/egovQr - регистрация процедуры упрощенного подписания пакета документов через QR или диплинки.

Ответ:

{
  "operationId": "12345",
  "status": "meta",
  "createdAt": 1668758020082,
  "expireAt": 1668758024082,
  "description": "Анкета и договор на подпись",
  "meta": [
    [
      {
        "name": "Анкета номер",
        "value": "1234"
      }
    ],
    [],
    [
      {
        "name": "Номер договора",
        "value": "1234"
      },
      {
        "name": "Контрагент",
        "value": "ТОО Контрагент"
      }
    ]
  ],
  "signIds": [17, 18, 19],
  "signatureEmailNotifications": {
    "to": ["user@example.com","other@example.com"],
    "doNotAttachDocuments": false,
    "language": "ru"
  },
  "errors": {
    "egov": "ошибка обмена данными",
    "sigex": "ошибка получения метки времени"
  }
}

operationId - строка, идентификатор зарегистрированной процедуры подписания;
status - строка, текущий статус процедуры, может принимать одно из следующих значений:
- "new" - новая операция, никаких действий еще не выполнялось;
- "meta" - пользователь сканировал QR код или кликнул на диплинк;
- "data" - приложение eGov mobile/business скачало документ для подписания;
- "done" - подписание выполнено успешно;
- "fail" - подписание не удалось;
createdAt - момент регистрации процедуры подписания в миллисекундах с UNIX Epoch;
expireAt - момент истечения срока действия процедуры подписания в миллисекундах с UNIX Epoch;
description - описание процедуры подписания установленное при регистрации;
meta - массив метаданных указанный при регистрации;
signIds - идентификаторы подписей, зарегистрированных в случае успешного завершения процедуры подписания;
signatureEmailNotifications - опциональный параметр, объект настроек для отправки уведомлений по электронной почте о регистрации новых подписей под документами пакета с полями:
- to - массив адресов электронной почты;
- doNotAttachDocuments - опциональное поле, позволяет отправлять уведомления без прикрепленных документов, по умолчанию false;
- language - опциональное поле, позволяет задать язык уведомления, поддерживаются строки "ru", "kk", "en" и их комбинации через "/", к примеру "kk/en";
errors - опциональный объект, содержащий информацию об ошибках, возникших при выполнении процедуры:
- egov - информация об ошибке полученной в процессе взаимодействия с eGov mobile/business;
- sigex - информация об ошибке полученной при обработке подписи.

`DELETE` `/api/package/{packageId}/egovOperation/{operationId}` - отмена процедуры подписания пакета документов

{packageId} - идентификатор пакета документов;
{operationId} - идентификатор процедуры подписания.

Позволяет отменять процедуры подписания зарегистрированные через POST /api/package/{packageId}/egovQr - регистрация процедуры упрощенного подписания пакета документов через QR или диплинки.

Ответ:

{
  "operationId": "12345"
}

operationId - строка, идентификатор зарегистрированной процедуры подписания.

# `GET` `/api/package?from=xxx&until=yyy&organization=true` - перечисление пакетов документов аутентифицированного пользователя или системы

from=xxx - с какого момента следует искать пакеты документов, значение следует указывать в миллисекундах с UNIX Epoch;
until=yyy - до какого момента следует искать пакеты документов, значение следует указывать в миллисекундах с UNIX Epoch;
organization=true - опциональный параметр, определяет следует ли искать пакеты документов физического лица или организации, по умолчанию false.

Ответ сервиса зависит от значения organization:

false - в этом случае сервис вернет пакеты документов относящиеся к аутентифицированному пользователю:
- при аутентификации с использованием сертификата физического лица сервис перечислит пакеты документов в правилах доступа к которым присутствует ИИН данного физического лица;
- при аутентификации с использованием сертификата сотрудника организации (юридического лица) сервис перечислит пакеты документов в правилах доступа к которым присутствует комбинация ИИН (сотрудника) и БИН (юридического лица);
- при аутентификации информационной системой по двустороннему mTLS сервис не перечислит ничего;
true - в этом случае сервис вернет пакеты документов относящиеся к организации:
- если пользователь прошел аутентификацию с помощью сертификата представителя организации (юридического лица) и у него в сертификате присутствуют полномочия указанные в настройках организации, либо в настройках организации указан ИИН данного сотрудника, либо сотрудник является первым руководителем, то сервис перечислит пакеты документов относящиеся к этой организации;
- при аутентификации информационной системой по двустороннему mTLS и если для этой информационной системы в настройках организации предоставлены права перечисления пакетов документов организации, то перечислит пакеты документов относящиеся к этой организации.

К пакетам документов организации относятся такие пакеты документов, в правилах доступа к которым присутствует БИН данной организации, а так же пакеты документов зарегистрированные информационными системами этой организации выполнившими аутентификацию по двустороннему mTLS.

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

Следует учитывать то, что данный метод возвращает ограниченное количество пакетов документов за один вызов, алгоритм получения всех пакетов документов:

получить первый блок пакетов документов установив желаемые from=xxx и until=yyy;
получить следующий блок пакетов документов установив until=storedAt из последнего элемента массива пакетов документов;
повторять до тех пор пока сервис не вернет пустой массив.

Ответ:

{
  "packagesTotal": 3,
  "packages": []
}

packagesTotal - количество пакетов документов удовлетворяющих запросу;
packages - массив объектов пакетов документов.

Структура объекта данных пакета документов:

{
  "packageId": "lQsqLBaS4nQAIIMm",
  "title": "package title",
  "description": "package description",
  "storedAt": 11111111111,
  "documentsIds": ["lQsqLBaS4nQAIIMm", "lQsqLBaS4nQAIIMm"]
}

packageId - идентификатор пакета документов;
title - заголовок пакета документов;
description - описание пакета документов;
storedAt - момент регистрации пакета документов в системе (миллисекунд с UNIX Epoch);
documentsIds - массив идентификаторов документов входящих в данный пакет.

The SIGEX portal uses cookies and other browser data storage technologies only for personalization of the user experience: displaying notifications, reminders and tips, as well as storing some settings. We do not use these technologies to track our users, collect information about them or display advertisements and do not provide such capabilities to third parties. Details are outlined in the Privacy Policy.

We conduct webinars about electronic documents, digital signatures and legal significance.

I want to attend a free webinar!

API: работа с пакетами документов

POST /api/package - регистрация пакета документов

GET /api/package/{packageId} - получение данных о зарегистрированном пакете документов

POST /api/package/{packageId} - добавление подписей к документам пакета

POST /api/package/{packageId}/notify - отправка уведомлений о пакете документов

POST /api/package/{packageId}/settings - изменение настроек пакета документов

GET /api/package/{packageId}/settingsAudit?lastEventId=X - аудит изменений настроек пакета документов

POST /api/package/{packageId}/egovQr - регистрация процедуры упрощенного подписания пакета документов через QR или диплинки

GET /api/package/{packageId}/egovOperation/{operationId} - получение статуса процедуры подписания пакета документов

DELETE /api/package/{packageId}/egovOperation/{operationId} - отмена процедуры подписания пакета документов

# GET /api/package?from=xxx&until=yyy&organization=true - перечисление пакетов документов аутентифицированного пользователя или системы

`POST` `/api/package` - регистрация пакета документов

`GET` `/api/package/{packageId}` - получение данных о зарегистрированном пакете документов

`POST` `/api/package/{packageId}` - добавление подписей к документам пакета

`POST` `/api/package/{packageId}/notify` - отправка уведомлений о пакете документов

`POST` `/api/package/{packageId}/settings` - изменение настроек пакета документов

`GET` `/api/package/{packageId}/settingsAudit?lastEventId=X` - аудит изменений настроек пакета документов

`POST` `/api/package/{packageId}/egovQr` - регистрация процедуры упрощенного подписания пакета документов через QR или диплинки

`GET` `/api/package/{packageId}/egovOperation/{operationId}` - получение статуса процедуры подписания пакета документов

`DELETE` `/api/package/{packageId}/egovOperation/{operationId}` - отмена процедуры подписания пакета документов

# `GET` `/api/package?from=xxx&until=yyy&organization=true` - перечисление пакетов документов аутентифицированного пользователя или системы