Перейти в сервис

Описание методов API сервиса подписания МИГ24

Авторизация
Асинхронные методы работы с сервисом
Работа с файлами
Формирование ЭП
Удаленное подписание
Визуализация ЭП
Проверка ЭП
Работа с сертификатами ЭП
Тестовая среда - https://test-sign.ntssoft.ru/ Продуктовая среда - https://mig24.online/
Запрос вашего код авторизации АПИ - info@mig24.ru
Telegram поддержки https://t.me/NTSsupport

Тестовый Swagger
https://test-sign.ntssoft.ru/api-docs
Продуктовый Swagger
https://mig24.online/api-docs

Авторизация

Для доступа к сервису необходимо указать следующий заголовок:
Authorization: Bearer <token>
Запросить token можно через info@mig24.ru или в Telegram https://t.me/NTSsupport
Предоставление доступа осуществляется на платной основе. При окончании оплаченного срока доступа авторизация возвращает ошибку: "Оплаченный срок доступа истек".

Асинхронные методы работы с сервисом

swagger

Общее описание работы асинхронных методов.
В приложении есть очереди запросов requests и ответов responses.
Пользователь отправляет запрос /api/requests с указанием самостоятельно сгенерированным идентификатора запроса requestId, указывает тип запроса requestType (GetStatus - получение результатов подписания) и UserFileId - id файла, для которого требуется получить результат подписания.

Если запрос был отклонен приложением, то пользователь получает отказ, корректирует запрос и отправляет снова.
Если запрос был принят (code 200), то он добавляется в очередь запросов, затем в очередь ответов добавляется ответ со статусом подтверждения начала обработки запроса со статусом WAITSIGN (Ожидание подписания файла).
Далее, после обработки в ИС хранения, будет добавлены остальные ответы с соответствующими статусами и информацией.

После успешной отправки асинхронного запроса в сервис пользователь может:
  • получить список идентификаторов на свои ответы, которые не помечены как удаленные из очереди ответов /api/responses
  • по идентификатору ответа получить все соответствующие данные /api/responses/{responseId}
  • отметить запрос удаленным из очереди ответов /api/responses/{responseId}.

Работа с файлами, загруженными в сервис

swagger

Загрузка файла в сервис - /api/v2/files/{id}
id (guid) - Идентификатор файла, присваивается пользователем самостоятельно

Загрузка "большого" файла в сервис - /api/v2/files/chink/{id}
id (guid) - Идентификатор файла, присваивается пользователем самостоятельно
Файл предварительно разбивается на части и каждая часть отправляется этим методом с одним и тем же Id. После окончания загрузки всех частей для их "склейки" в один файл выполняется /api/v2/files/chink/complete/{id}

Получение списка файлов, загруженных и хранящихся в сервисе авторизовавшимся пользователем - /api/v2/files
Возвращается массив сведений.
Для каждого файла:
id: - Идентификатор файла в сервисе
contentType: - Тип файла(null, text/xml, application/pdf, application/octet-stream)
name: - Название файла
creationDateTime: - Дата время загрузки файла в сервис

Получение файла из сервиса - /api/v2/files/{id}/file
id: - Идентификатор файла в сервисе

Получение информации о файле в сервисе - /api/v2/files/{id}/file
id: - Идентификатор файла в сервисе
name: - Название файла
contentType: - Тип файла(null, text/xml, application/pdf, application/octet-stream)
regId - Идентификатор для доступа к файлу через WEB
size: - Размер в байтах
sha1: - Хеш файла

Разметка загруженного файла PDF без подписания - /api/v2/pdf/fields
files-[] - Список идентификаторов файлов, которые необходимо разметить
signatureCount - Количество подписей в документе
isNeedCertification - Необходимость сертификации файла сервисом
stampId- Идентификатор штампа, обязателен, если не заполняется Fields
fields - object[] - Список полей для встроенного подписания
fieldName- Наименование поля подписания
stampId- Идентификатор штампа, обязателен, если не заполнен Size
size - object[] - Размеры поля подписания
width - Ширина в мм
height - Высота в мм
stampPosition - Позиция штампа в документе
pageNumber - Номер страницы
topLeftX - Смешение от верхнего левого угла страницы по оси X
topLeftY - Смешение от верхнего левого угла страницы по оси Y

Результат выполнения - идентификатор файла (guid)

Формирование электронной подписи

swagger

Формирование любой КЭП состоит из нескольких этапов:
  • Загрузка документа в сервис /api/v2/files/{id}
  • Подготовка документа в сервисе - вычисление и возврат хэша документа
  • Подпись полученного хеша с помощью функций CryptoPro CSP или функции плагина NTSsoft crypto extension.
  • Отправка подписанного хеша в сервис, для окончательного формирования подписи
  • Скачивание полученной подписи или документа с подписью /api/v2/files/{id}/file

Подготовка документа к подписи - /api/v2/sign/TYPE/prepare
Для Type:
  • attached - прикрепленная подпись,
  • detached - открепленная подпись,
  • contract - договор,
  • fsrar - ФСРАР,
  • quotation - котировка,
  • arbitr - Мой Арбитр
token - Идентификатор сессии подписания, генерируется инициатором
files - [] - Список идентификаторов файлов подписываемых документов
certificate - Сертификат для подписания

Для Type: pdf
token - Идентификатор сессии подписания, генерируется инициатором
files - [] - Список идентификаторов файлов подписываемых документов
stampId - Идентификатор штампа
certificate - Сертификат для подписи
isInvisible - Установление невидимой подписи для сертификации документа
signatureCount - Количество подписей
signatureParams - object[] - Список параметров подписи
stampId - guid -Идентификатор штампа
stampPosition - object[] - Позиция штампа в документе
pageNumber - int - Номер страницы
topLeftX - double - Смешение от верхнего левого угла страницы по оси X
topLeftY - double - Смешение от верхнего левого угла страницы по оси Y
cadesType - Тип CAdES (CadesBes - обычная, CadesXLongType1 - с меткой времени). Если указать при подготовки документа, то размер места под подпись будет соответствовать размеру подписи для CadesBes

Возвращается массив хешей для подписания.

Подписание Хеш на стороне пользователя
Пример подписания в CryptoPro. Плагин должен быть установлен и включен на месте подписания.

Завершение подписи документа - /api/v2/sign/TYPE/finish
token - Идентификатор сессии подписания
cadesType - Тип CAdES (CadesBes - обычная, CadesXLongType1 - с меткой времени)
files - object[] - Список подписей файлов документов
fileId - Идентификатор файла
signature - Подпись хеша файла
signedByMchdInfoId - Идентификатор МЧД в сервисе МЧД.МИГ24
cadesType - Тип CAdES (CadesBes - обычная, CadesXLongType1 - с меткой времени)
isBase64 - формат подписи, true - Base64, false - DER
isOneLine - при true - подпись в одну строку
isZipBulkSignature - вернуть результат в виде архива

Возвращается массив данных о подписях:
FileId - Идентификатор файла документа
SignatureId - Идентификатор файла подписи
FileName - Название подписанного файла


Примеры работы со встроенными подписями в PDF
Пример подписания с 1 подписью на отдельной странице
Пример подписания с 2 подписями в указанном месте
Мультиподпись с сертификацией



Удаленное подписание

swagger

Документ, загруженный в сервис можно подготовить для его удаленного подписания:
Базовый сценарий:
  • Загружаем нужные файлы в сервис методом /api/v2/files/{id}
  • Для файла формата pdf (при подписании встроенной КЭП) проводим разметку документа методом /api/v2/pdf/fields Если подходит стандартная разметка (синий штамп в левом нижнем углу последнего листа документа), то метод можно пропустить.
  • Производим подготовку файла для подписания методом /api/v2/shared-files
  • Формируем ссылку для подписания https://mig24.online/registry/files/{RegInfoId} или отправляем файл на подписание в мобильное приложение /api/v2/share/mobile-app
  • Получаем результаты подписания /registry-infos/{RegInfoId}/last-file

Подготовка файла для подписания - /api/v2/shared-files
"FileId"*: guid - Id документа в сервисе, требующего подписания
"UserId": guid - id пользователя сервиса, отправляющего документ на подписание,
"Visualization": "FileId": guid - id файла визуализации подписываемого документа
"MchdInfoId": - id МЧД из сервиса МЧД.МИГ24,
"TargetSignatureType"*: - тип подписи (Attached/Detached/Pdf),
"ServiceName"*: - название сервиса, отправившего документ на подписание,
"IsBase64"*: true - подпись в base64, иначе DER,
"IsOneLine": true - подпись в одну строку (true/false/null)
"CadesType"*: "None, CadesBes, CadesT, CadesXLongType1.
"SignerRequirements": Параметры подписания:
  • "SignerOrgViewName": название компании подписанта
  • "SignerViewName": ФИО подписанта
  • "IssuerViewName": название издателя сертификата КЭП подписанта,
  • "OrganizationId": guid id организации подписанта в сервисе
  • "SignBeforeDateTime": ограничение подписания до даты/время,
  • "Issuer": "Ogrn": Ограничение по ОГРН издателя сертификата подписанта
  • "Subject": набор ограничений подписанта: ( "InnFl": ИНН ФЛ, "InnUl": ИНН ЮЛ, "Snils": СНИЛС: "Ogrn": ОГРН ЮЛ, "Ogrnip": ОГРНИП, "Name": название ЮЛ).
После успешной подготовки возвращается RegInfoId


Отправка файла на подписание в мобильное приложение /api/v2/share/mobile-app
"RequestId": guid - id асинхронного запроса
"AccessCode": "код доступа (номер телефона) или "Snils": СНИЛС - по этим данным производится идентификация пользователя - подписанта, кому нужно отправить файл на подписание
"FileId":guid - id подписываемого и подготовленного файла

Перед отправкой файла в мобильное приложение желательно убедиться в том, что у вашего адресата уже подключено приложение МИГ24. Для этого можно воспользоваться:
/api/v2/user/mobile/check

Визуализация КЭП на PDF

swagger

Функционал предназначен для визуализации (создания штампа) квалифицированной электронной подписи на документе формата pdf, подписанного открепленной или прикрепленной подписью.
  • Загружаем необходимые файлы - /api/v2/files/{id} (подписанный документ, подписи, файлы для включения внутрь pdf)
  • Производим визуализацию - /api/v2/visual/signatures
  • Скачиваем полученный файл - /api/v2/files/{id}/file
Id стандартного штампа (StampId) сервиса 61501264-CDCF-45B5-9EB6-300BF61CBBBF
Если необходим свой вариант штампа визуализации КЭП, он настраивается под доступом web-пользователя в разделе Профиль. После настройки там же можно получить id штампа, для его использования в api.

Визуализация открепленной (отсоединенной) КЭП - /api/v2/visual/signatures
"SrcFileId": Id загруженного в сервис подписанного файла в формате pdf
"Attachments": массив id файлов, необходимых включить внутрь создаваемого файла визуализации
"SigFileId": Id загруженной в сервис электронной подписи файла для штампа
"StampId": ID штампа сервиса, который будет использован для визуализации
"StampPositions": - массив местоположение штампов в создаваемом файле
  • "PageNumber": номер страницы в документе (начинается с 1),
  • "TopLeftX": координата X левого верхнего угла штампа
  • "TopLeftY": координата Y левого верхнего угла штампа
  • "StampScale": масштаб штампа (1- 100%, 0.2-20%, 1.6-160% и т.д.)
Визуализация прикрепленной (присоединенной) КЭП - /api/v2/visual/attached/signatures
"SrcFileId": Id загруженного в сервис подписанного файла в формате pdf
"Attachments": массив id файлов, необходимых включить внутрь создаваемого файла визуализации
"SigFileId": null, передавать не нужно
"StampId": ID штампа сервиса, который будет использован для визуализации
"StampPositions": - массив местоположение штампов в создаваемом файле
  • "PageNumber": номер страницы в документе (начинается с 1),
  • "TopLeftX": координата X левого верхнего угла штампа
  • "TopLeftY": координата Y левого верхнего угла штампа
  • "StampScale": масштаб штампа (1- 100%, 0.2-20%, 1.6-160% и т.д.)

Проверка электронной подписи

swagger

Сервис позволяет провести проверку следующих типов КЭП:
  • проверка прикрепленной подписи - /api/v2/verify/attached
  • проверка открепленной подписи - /api/v2/verify/detached
  • проверка подписи PDF - /api/v2/verify/pdf
Результат проверки возвращается в виде набора данных:
"DatetimeStr": Дата время подписания в виде строки "19.03.2024 17:12:36 +05:00",
"IsInvisible": false - не используется для API,
"Signer": Информация о подписанте
"DateTime": Дата время подписания "2024-03-19T17:12:36+05:00",
"Timestamp": Информация о метке времени
"IsValid": Признак верна ли подпись, true/false,
"Error": - Ошибка, если подпись не верна, например, "Документ содержит неверную подпись"
"Thumbprint": - Отпечаток сертификата

  • проверка подписи в документе ЭД2 ФТС - /api/v2/verify/fts
"HasError": значение наличия ошибки проверки загруженного документа
"ErrorMessage": текст ошибки
"EnvelopeID": идентификатор сообщения ЭД2
"MessageType": тип сообщения ЭД2
"MessageDescription":
"SignatureCount": количество подписей в сообщении
"TotalMathValidity": Общая валидность пакета
"TotalMathValidity": Общая математическая корректность пакета
"SignatureLimit":
"TotalSignatureCount":
"HasHeader": значения наличия заголовков EnvelopeID или MessageType или MessageDescription
"SignInfos":

"Id":
"Gost": стандарт вычисления хэш функции

"KeyInfoDigestValid": валидность Хэш раздела KeyInfo
"ObjectDigestValid": валидность Хэш раздела Object
"SignatureValid": валидность подписи
"DigestAlgorithmMatch": валидность алгоритмов хэширования
"SignatureAlgorithmMatch": валидность алгоритмов подписи
"Validity":
"CertificateInfo": Информация о сертификате ЭП
{
"IsValid": значение общей проверки сертификата сертификата
"VerificationErrorMessage": текст ошибки проверки подлинности сертификата. Например, "Неверный период действия сертификата"
"RequestError":
"HasRequestError":
"Subject": "Иванов Александр Алексеевич, ООО \"НТСсофт\""
"Issuer": издатель
"NotBefore": "2022-12-23T09:52:49+05:00"
"NotAfter": "2023-12-23T10:02:49+05:00"
"Thumbprint": отпечаток сертификата
"IsGost": значение, что по ГОСТу
"HasCertificateInfo": значения что есть информация о сертификате
"IsSsl": значение, что сертификат SSL
"StructureErrors": ошибки проверки структуры сертификата (массив строк)
"IsVerified": подлинность сертификата в виде статуса
"HasStructureErrors": значение наличия ошибок структуры сертификата
"IsQualified": неквалифицированный сертификат или квалифицированный
"AuthenticityStr": подлинность сертификата в виде статуса. Например: "НЕ ПОДТВЕРЖДЕНА"
"StatusStr": текстовое представление статуса проверки. Например: "Неверный период действия сертификата"
"CertificateBase64": сертификат в base64
}

Работа с сертификатами ЭП

swagger

Получить информацию из сертификата - /api/certificate/info
Проверить сертификата - /api/certificate/validate
Проверить SSL сертификат - /api/certificate/validate-ssl