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 - массив идентификаторов документов входящих в данный пакет.

SIGEX порталы браузерде cookie файлдары мен басқа деректерді сақтау технологияларын тек жекелендіру үшін пайдаланады: хабарландыруларды, еске салуларды және кеңестерді көрсету, сондай-ақ кейбір параметрлерді сақтау үшін. Біз бұл технологияларды өз пайдаланушыларымызды қадағалау, олар туралы ақпарат жинау немесе жарнама көрсету үшін пайдаланбаймыз және үшінші тараптарға мұндай мүмкіндіктер бермейміз. Егжей-тегжейлер Құпиялылық саясатында баяндалған.

Біз электрондық құжаттар, ЭЦҚ және заңды маңызы туралы вебинарлар өткіземіз.

Тегін вебинар тыңдағым келеді!

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` - перечисление пакетов документов аутентифицированного пользователя или системы