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

Описание методов 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}
  • Для файла формата 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 подписываемого и подготовленного файла

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

swagger

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

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

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

Получение информации о файле в сервисе - /api/v2/files/{id}/file
"Id": - id файла в сервисе
"ContentType": - тип файла(null, text/xml, application/pdf, application/octet-stream)
"Name": - название файла
"RegId": null ??
"Size": размер в байтах
"Sha1": "4C09CC37B09F988F60D58A127B759F741A3DB6F5" ??

Разметка загруженного файла PDF без подписания - /api/v2/pdf/fields
  • Files- guid[] - Список идентификаторов файлов
  • Fields - object[] - Список объектов с параметрами полей для подписи
  • StampId- guid - Идентификатор штампа, обязателен, если отсутствует Size
  • FieldName- string - Название поля
  • Size - object - Размеры поля
  • Width - double - Ширина в мм
  • Height - double - Высота в мм
  • StampPosition - object - Позиция штампа в документе
  • PageNumber - int - Номер страницы
  • TopLeftX - double - Смешение от верхнего левого угла страницы по оси X
  • TopLeftY - double - Смешение от верхнего левого угла страницы по оси Y
Результат выполнения - идентификатор файла

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

Подготовка документа к подписи - /api/v2/sign/TYPE/prepare
Если Type принимает значение:
  • Договор - contract
  • Прикрепленная подпись - attached
  • Открепленная подпись - detached
  • ФСРАР - fsrar
  • Котировка - quotation
  • Мой Арбитр - arbitr
Token - guid - Идентификатор сессии подписания, генерируется инициатором
Files - guid[] - Список идентификаторов файлов документов
Certificate - Base64 - Сертификат для подписи

Если type принимает значение pdf:
  • Token - guid - Идентификатор сессии подписания
  • Files - guid[] - Список идентификаторов файлов
  • StampId - guid - Идентификатор штампа
  • Certificate - Base64 - Сертификат для подписи
  • IsInvisible - bool - Невидимая подпись для сертификации документа
  • SignatureCount - int - Количество подписей, обязателен при отсутствии SignatureParams
  • SignatureParams - object[] - Список параметров подписи
  • StampId - guid -Идентификатор штампа, обязателен при отсутствии StampId родительского объекта
  • StampPosition - object - Позиция штампа в документе
  • PageNumber - int - Номер страницы
  • TopLeftX - double - Смешение от верхнего левого угла страницы по оси X
  • TopLeftY - double - Смешение от верхнего левого угла страницы по оси Y
  • CadesType - string - Тип CAdES (CadesBes - обычная, CadesXLongType1 - улучшенная, с меткой времени). Если указать при подготовки документа, то размер места под подпись будет соответствовать размеру подписи для CadesBes
Возвращается массив хешей для подписания.

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

Завершение подписи документа - /api/v2/sign/TYPE/finish
  • Token - guid -Идентификатор сессии подписания
  • CadesType - string - Тип CAdES (CadesBes - обычная, CadesXLongType1 - улучшенная, с меткой времени)
  • Files - object[] - Список подписей файлов документов
  • FileId - guid - Идентификатор файла
  • Signature - Base64 - Подпись хеша файла
  • IsTryFinish - bool - Если требуется попытаться подписать документ TYPE contract улучшенной подписью, а при неудаче - обычной
Возвращается массив данных о подписях:
  • FileId - guid - Идентификатор файла документа
  • SignatureId - guid - Идентификатор подписи
  • FileName - string - Название подписанного файла
Примеры работы со встроенными подписями в PDF
Пример подписания с 1 подписью на отдельной странице
Пример подписания с 2 подписями в указанном месте
Мультиподпись с сертификацией



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

swagger

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