Перейти в сервис
Инструкция
Стоимость
Информация
8 800 333 22 05
МИГ24 Электронное подписание документов
ЭДО24 Электронный документооборот
МЧД24 Машиночитаемые доверенности
МИГ24 Управление организацией
Сервисы экосистемы МИГ
Мы будем рады ответить вам на все ваши вопросы по работе сервиса подписания документов

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

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

Актуальная версия - V2
Тестовый 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.
Пользователь отправляет запрос POST /api/requests с указанием самостоятельно сгенерированным идентификатора запроса requestId, указывает тип запроса requestType (GetStatus - получение результатов подписания) и UserFileId - id файла, для которого требуется получить результат подписания.

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

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

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

swagger

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

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

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

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

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

POST "Слияние" нескольких КЭП в один файл - /api/v2/files/signature/append
signedFile - идентификатор подписанного файла (нужен для проверки правильности КЭП)
signatures - массив идентификаторов подписей, которые необходимо слить в один sig.

POST Разметка загруженного файла 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

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

Подготовка документа к подписи - POST /api/v2/sign/TYPE/prepare
Для Type:
  • attached - прикрепленная подпись,
  • detached - открепленная подпись,
  • contract - договор,
  • fsrar - ФСРАР,
  • quotation - котировка,
  • arbitr - Мой Арбитр
  • rosreestr - Росреестр
token - Идентификатор сессии подписания, генерируется инициатором
files - [] - Список идентификаторов файлов подписываемых документов
certificate - Сертификат для подписания - строка в base64
cadesType - Тип CAdES
  • CadesBes - обычная
  • CadesT - с меткой времени (TSP)
  • CadesXLongType1 - с меткой времени (TSP) и с меткой статуса сертификата (OCSP)
  • CadesA - архивный формат
Для Type: pdf
token - Идентификатор сессии подписания, генерируется инициатором
files - [] - Список идентификаторов файлов подписываемых документов
stampId - Идентификатор штампа
certificate - Сертификат для подписи - строка в base64
isInvisible - Установление невидимой подписи для сертификации документа
signatureCount - Количество подписей
signatureParams - object[] - Список параметров подписи
stampId - guid -Идентификатор штампа
stampPosition - object[] - Позиция штампа в документе
pageNumber - int - Номер страницы
topLeftX - double - Смешение от верхнего левого угла страницы по оси X
topLeftY - double - Смешение от верхнего левого угла страницы по оси Y

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

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

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

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


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


POST Получение файла из прикрепленной подписи - /api/v2/sign/attached/extract

POST Улучшение КЭП до заданного формата - /api/v2/enhance-signatures
Метод позволяет улучшить / преобразовать КЭП в заданный формат (CadesBes / CadesT / CadesXLongType 1 / CadesA). Улучшение возможно только для КЭП с действующим сертификатом и при наличии в УЦ, выдавшем сертификат сервиса OCSP.
Пример использования в web: https://sign.mig24.online/enhance

  • Загружаем файл подписи в сервис - POST /api/v2/files/{id}
  • Выполняем метод улучшения POST /api/v2/enhance-signatures { "signatureFileId": "3fa85f......6afa6", "cadesType": "CadesA"}
  • Скачиваем файл подписи в заданном формата GET /api/v2/files/{id}/file
Удачное улучшение:
{
"id": "825606fe-4d3e-4a9e-a614-2387666009f0",
"name": "07-b83c-289dbf7eb70f.sig.enhanced.sig"
}

При невозможности выполнения улучшения вернется ошибка.
Пример:{
"type": "/client-error/bad-request",
"title": "BadRequest",
"status": 400,
"detail": "Сертификат был отозван поставщиком этого сертификата."
}

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

swagger

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

Подготовка файла для подписания -POST /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


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

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

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

swagger

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

Визуализация одной открепленной (отсоединенной) КЭП POST /api/v2/visual

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

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

swagger

Сервис позволяет провести проверку следующих типов КЭП:
POST проверка прикрепленной подписи - /api/v2/verify/attached
POST проверка открепленной подписи - /api/v2/verify/detached
POST проверка подписи PDF - /api/v2/verify/pdf
Результат проверки возвращается в виде набора данных:
"IsValid": признак верна ли подпись, true/false,
"signer": блок информации о подписанте, данные их сертификата КЭП и его статус
"cadesType": формат подписи
"signDateTime": дата время подписания
"timestamp": блок информации о метке времени TSP включая "dateTime": дата время метки времени и информация о сертификате TSP
"evidenceTimestamp": блок информации о метке статуса сертификата КЭП OCSP, включая дату время этой проверки "producedAt" и информация о сертификате OCSP

POST проверка подписи в документе ЭД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
}

POST Проверка КЭП, загруженных в сервис /api/v2/verify/math/signatures
Требует предварительной загрузки файла подписи и при необходимости проверки соответствия подписи документу - подписанного документа.
возвращает массив сведений о проверке КЭП

POST Пакетная проверка КЭП /api/v2/verify/pack
Метод самостоятельно группирует подписи и подписанные документы и производит из проверку.

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

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

POST Определить необходимость МЧД - /api/v2/certificate-verification
Указывается ИНН/ОГРН/тип подписанта документа и загружается сертификат КЭП.
Метод возвращает информацию о возможности подписания документа этим сертификатом и необходимости подтверждения полномочий подписанта.
Например, если ИНН 6670237020, тп - ЮЛ, а сертификат от ФЛ, то получаем
{ "isValid": true, "isQualified": true, "error": null, "isNeedMchd": true}
если сертификат на директора другого ЮЛ и отозван:
{ "isValid": false, "isQualified": false, "error": "Сертификат отозван", "isNeedMchd": true}

Сценарий многостороннего подписания
swagger

Сервис позволяет организовать процесс многостороннего подписания загруженного документа сотрудниками организаций - Абонентами ЭДО.МИГ24.
Блок методов Mig24SharedFileApi

  • /api/v1/mig24/users - Запрос идентификатора подписанта как сотрудника необходимой организации или как физического лица. По СНИЛС предоставляется перечень организаций, в которых указанное лицо добавлено в сервисе ЭДО.МИГ24 как сотрудник.
Для каждой найденной записи возвращается:
Сведения о подписанте ("id": идентификатор, "name": ФИО, "snils": СНИСЛ, "inn": ИНН, "email":email, "phone": телефон) и сведения об организации "organization": { "id": идентификатор", "name": названия, "ogrn": ОГРН, "inn": ИНН, "kpp": КПП}

  • /api/v1/mig24/files/{id} - Загрузка необходимого файла на сервер.
Указывается идентификатор (guid)

  • /api/v1/mig24/shared-file Подготовка документа к подписанию.
Необходимо подготовить запрос
"fileId": Идентификатор загруженного файла, который необходимо подписать,
"targetSignatureType": формат подписи "Detached" открепленная,
"signerRequirements": - перечень подписантов {
"signerOrgUserId": идентификатор подписанта,
"notificationEmail": email подписанта -при указания данного параметра сервис отправит на указанный email уведомления о необходимости подписать документ }
"signatureSettings": параметры подписи {
"isBase64": true,
"isOneLine": true,
"cadesType": "cadesbes",
"extractFromZip": true,
"typeSigning": "None" }
"isPaid": true - проставление оплаченности подписания документа (необходимое для оплаты количество пакетов спишется с организации, инициатора подписания) "organizationId": идентификатор организации - инициатора подписания.

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

При необходимости подгрузить КЭП к загруженному для подписания файлу, созданную не в сервисе ЭДО.МИГ24 можно использовать метод /api/v1/mig24/shared-file/append, предварительно загрузив файл подписи через /api/v1/mig24/files/{id}
{ "userFileInfos": [ { "userFileId": идентификатор файла загруженной подписи, "userFileType": описание типа загруженного файла, "signerOrgUserId": идентификатор подписанта } ], "sharedFileId": идентификатор подготовленного для подписания файла}
При добавлении подписи этим методом сервис проверит корректность этой подписи, действительность сертификата КЭП и при положительном результате присоединит эту подпись к документу в сервисе.

После каждого успешного подписания документа (или добавлении) сервис формирует соответствующее событие в очередь подписания /api/v1/events/mig24-signature-completed
В событии можно получить
"EventId": идентификатор события, "SharedFileId": идентификатор подписанного документа, "SignatureUserFileId": идентификатор файла подписи, "SignerOrgUserId": идентификатор подписанта, "CreationDateTime": дата время подписания" },
После успешного получения информации о событии необходимо подтвердить получение методом /api/v1/events/{eventId}/ack или /api/v1/events/ack

Нужный файл подписи скачивается /api/v1/mig24/files/{id}/file

При необходимости в любой момент можно скачать архив, содержащий подписываемый документ и все файлы подписей, сформированные на момент запроса - /api/v1/mig24/shared-file/{id}/last-file

После завершения подписания документа всеми сторонами можно скачать справку.

Получение тестового комплекта ключей ЭП
(исключительно для работы с тестовой средой)

Для тестирования сервисов МИГ24 можно использовать тестовый ключ и сертификат ЭП, созданные в следующем порядке:

1.В сервисе МИГ24 создается запрос на сертификат
Потребуется NTSsoft browser plugin. Расширение для его работы: для Chrome, для Edge

При создании запроса желательно указывать реальные данные, чтобы там, где необходимо, проходила проверка на математическую корректность и соответствие сведений ЕГРЮЛ (ЕГРИП).
Данные для запроса можно заполнить вручную или подгрузить из уже существующего сертификата ЭП - кнопка импорта в правом верхнем углу.

Ключевой контейнер можно сохранить как на съемный носитель, так и в реестр.

2.После создания запроса необходимо нажать появившуюся внизу страницы кнопку "Выпустить сертификат от Тестового УЦ ООО "КРИПТО-ПРО"".

В открывшемся окне нажмите ссылку "скопировать запрос", вставьте (ctrl+v) текст запроса в поле "Сохраненный запрос". Нажмите кнопку "Выдать" и, далее, "Загрузить сертификат".

Также, запрос можно сохранить на диск (кнопка в левом нижнем углу формы создания запроса), загрузить запрос по одной из ссылок:
https://testgost2012.cryptopro.ru/certsrv/certrqxt.asp - загрузили запрос, получили сертификат.
https://testca2012.cryptopro.ru/UI/Default.aspx - работа по ГОСТ, требует регистрации

3.После получения сертификата необходимо его установить в хранилище "Личные".
Обязательно необходимо убедиться, что корневой сертификат также уже установлен и цепочка доверия выстроена.