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

Презентация возможностей API сервиса сервиса https://m4d.mig24.ru/api

Тестовая среда - https://test-mchd.ntssoft.ru/
Тестовый ЦПРР - https://poar.cprr-it.weintegrator.com/emchd
Тестовый Swagger
https://test-mchd.ntssoft.ru/api-docs или https://test-mchd.ntssoft.ru/api-doc.html
Получение тестовой КЭП https://testca2012.cryptopro.ru/UI/Default.aspx

Запрос вашего код авторизации АПИ - info@mig24.ru
Telegram поддержки https://t.me/NTSsupport

Продуктовая среда - https://m4d.mig24.online/
Продуктовый Swagger
https://m4d.mig24.online/api-docs или https://m4d.mig24.online/api-doc.html

Авторизация

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

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

swagger

Общее описание работы асинхронных методов.
В приложении есть очереди запросов requests и ответов responses.
Пользователь отправляет запрос /api/requests с указанием самостоятельно сгенерированным идентификатора запроса requestId, указывает тип запроса requestType:
  • Mchd- регистрация МЧД
  • Revocation - отмена МЧД
  • GetStatus - получение статуса МЧД
  • GetMchd - получение архива с файлами МЧД
  • SubscribeStatus - Подписка на состояние статуса МЧД
svedSyst:
  • CPRR -ЦПРР ФНС
  • MIG24 - МЧД.МИГ24
  • SFR - Социальный Фонд России
и дополнительные сведения (файлы или номер доверенности).

Если запрос был отклонен приложением, то пользователь получает отказ, корректирует запрос и отправляет снова.
Если запрос был принят (code 200), то он добавляется в очередь запросов, затем в очередь ответов добавляется ответ со статусом подтверждения начала обработки запроса со статусом AWAIT_SENDING_TO_CPRR (ОЖИДАНИЕ ПЕРЕДАЧИ ЗАПРОСА).
Далее, после обработки в ИС хранения, будет добавлены остальные ответы с соответствующими статусами.

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

Mchd - регистрация МЧД
Для запроса загрузки МЧД остановка работы запроса заканчивается при получении одного из следующих статусов: CREATED (ЗАРЕГИСТРИРОВАНА), ACTIVE (ДЕЙСТВУЕТ), REJECTED (ОТКАЗ В РЕГИСТРАЦИИ), REVOKED (ДЕЙСТВИЕ ПРЕКРАЩЕНО), EXPIRED (ДЕЙСТВИЕ ИСТЕКЛО).

Revocation - отмена МЧД
Для запроса загрузка заявления на отмену остановка работы запроса произойдет при получении одного из следующих статусов: REJECTED (ОТКАЗ В РЕГИСТРАЦИИ), REVOKED (ДЕЙСТВИЕ ПРЕКРАЩЕНО), EXPIRED (ДЕЙСТВИЕ ИСТЕКЛО).

GetStatus - получение статуса МЧД
Работа запроса на однократное получение статуса по номеру МЧД будет остановлена после получения статуса. В очередь ответов будет добавлен соответствующий ответ.
Возможные статусы МЧД:

AWAIT_SENDING_TO_CPRR - ОЖИДАНИЕ ПЕРЕДАЧИ ЗАПРОСА

SEND_TO_CPRR - ЗАПРОС ПЕРЕДАН

SEND_TO_CPRR_ERROR - ОШИБКА ПРИЕМА ЗАПРОСА

PROCESSING - ОЖИДАНИЕ ПОДТВЕРЖДЕНИЯ

REJECTED- ОТКАЗ В РЕГИСТРАЦИИ

CREATED - ЗАРЕГИСТРИРОВАНА

ACTIVE - ДЕЙСТВУЕТ

REVOKED - ДЕЙСТВИЕ ПРЕКРАЩЕНО

EXPIRED - ДЕЙСТВИЕ ИСТЕКЛО

UNDEFINED - НЕОПРЕДЕЛЕН


Любой запрос, по которому пришел ответ - ошибка, будет остановлен. Содержание ошибки будет предоставлено в ответе в виде строки json или в виде строки текста, если получен не json.

GetMchd - получение архива с файлами МЧД
При запросе архива МЧД - когда архив МЧД готов к скачиванию, то возвращается ответ со статусом READY_FOR_DOWNLOAD - ГОТОВА ДЛЯ СКАЧИВАНИЯ.
В ответе присутствуют ContentType и MchdFileId
Чтобы скачать файл следует использовать синхронный метод /api/m4d/files/{mchdFileId}
Чтобы получить только полномочия и статус (не скачивая архив) следует использовать синхронный метод /api/m4d/files/{mchdFileId}/check-powers
В случае, если такой МЧД нет в ИС хранения, то вернется NOT_FOUND - НЕ НАЙДЕНА.

Пример архива с файлами МЧД

SubscribeStatus - Подписка на состояние статуса МЧД
Можно добавить в сервис подписки любую МЧД.
Потребуется ее номер и место хранения.
После начала подписки сразу будет возвращен текущий статус МЧД.
Далее сервис самостоятельно следит за статусом этой МЧД в месте ее хранения и при любом его (статусе) изменении формирует для инициатора подписки соответствующее сообщение с новым статусом.
Подписка на МЧД отменяется автоматически при получении статусов "Действие прекращено", "Отказ в регистрации" или "Действие истекло".
Данный функционал призван существенно снизить необходимость постоянно опроса статусов МЧД из системы, где они проверяются и используются и получать только сообщения, когда статус действительно изменился.
ВАЖНО! Если при первом запросе вернется статус NOT_FOUND - НЕ НАЙДЕНА, отслеживание статуса такой МЧД все равно начнет работать. Это сделано для случая, когда номер МЧД уже есть, но МЧД еще не разместили в ИС Хранения, и как только она там будет зарегистрирована - сервис оповестит об этом. Если следить за отсутствующей (ожидать появления) МЧД не нужно, то от такой МЧД нужно отписаться вручную.

UnsubscribeStatus - Ручная отписка.
(requestId, requestType, svedSyst, mchdNumber)
На запрос приходит два асинхронных ответа:
Первый со статусом AWAIT_SENDING_TO_CPRR (0, ОЖИДАНИЕ ПЕРЕДАЧИ ЗАПРОСА В СИСТЕМУ ХРАНЕНИЯ)
Второй со статусом MCHD_STATUS_UNSUBSCRIBE (12, ПОДПИСКА ОТМЕНЕНА)

Отправить запрос для МЧД из сервиса - /api/requests/send-created
Отправляет запрос на выполнение нужного действия для МЧД, созданной в сервисе.
mchdInfoId - Идентификатор МЧД в сервисе
requestType - Тип запроса: Mchd
Метод работает пока только для МЧД СФР. Результат выполнения метода можно получить запросив актуальный статус МЧД в сервисе.

Методы работы со справочниками (полномочия)

swagger

Методы предназначены для получения актуальной (или нужной) версии справочников полномочий, ограничений и значений для ограничений полномочий в соответствии с Единой системы нормативной справочной информации (ЕСНСИ) и других справочников полномочий для МЧД.

Получение кодов доступных справочников - /api/esnsi/codes
Коды справочников, доступные для получения:
POWER_B2B - Код справочника полномочий B2G (для формата ФНС)
POWER_B2G - Код справочника полномочий B2B (для формата 002)
POWER_PWR_CLASS - Код справочника полномочий (для единого формата (003))
POWER_PWR_RESR - Код справочника ограничений полномочий (для единого формата)
POWER_PWR_RESTR_VALUE - Код справочника значений для ограничений полномочий
POWER_SFR - Код справочника полномочий Социального Фонда России (СФР) (скоро).

Получение последней версии справочника -/api/esnsi/{code}/last-version

Получений доступных версий справочника -/api/esnsi/{code}/versions

Получение zip-архива со справочником ЕСНСИ в формате xml -/api/esnsi/data

Создание/загрузка МЧД в сервисе, в том числе через json

swagger

Создание пустой доверенности в формате B2G ФНС (5.01) - /api/b2g
Возвращается идентификатор mchdInfoId созданной МЧД.
!!! формат 5,02 не поддерживается для передачи через ЦПРР ФНС.

Создание пустой доверенности B2B (002) - /api/b2b
Возвращается идентификатор mchdInfoId созданной МЧД

Создание пустой доверенности в едином формате (003) - /api/em4d
Возвращается идентификатор mchdInfoId созданной МЧД

Создание МЧД через загрузку файлов xml и sig - /api/import?validate=true
validate - проверить xml по xsd-схеме. Пока нет поддержки проверки для единого формата, поэтому или не указывать validate или validate=false.
Допускается загрузка массива файлов неподписанных МЧД в формате xml.
При загрузке подписанной МЧД возможна загрузка только одного комплекта xml + sig, при этом происходит проверка на наличие в сервисе МЧД с таким же номером (guid).
Возвращается идентификатор mchdInfoId созданной МЧД

Создание МЧД через загрузку json - /api/import/json
Возвращается идентификатор mchdInfoId созданной МЧД. Для загрузки используется модель нужного типа МЧД (B2G, B2B, Единый, СФР).

Изменение (замена данных) существующей неподписанной МЧД - /api/import/json?mchdInfoId={mchdInfoId}
mchdInfoId - идентификатор МЧД в которой заменяются данные
модель аналогична той, что используется при создании МЧД через json.

Создание МЧД #ФТС через загрузку json - /api/import/json-for-fts
Возвращается идентификатор mchdInfoId созданной МЧД.
Общая схема запроса, Доверитель ЮЛ+ФЛ, Доверитель ИП+ФЛ
Помимо стандартных данных для МЧД, необходимы регистрационные данные ЭД2. Для получения регистрационных данных необходимо обратиться в техническую поддержку НТСсофт.

Подписание МЧД / отмена МЧД

swagger

Подписание МЧД, размещенной в сервисе можно произвести следующими способами:
  • выгрузить xml, подписать своими средствами, подгрузить обратно в сервис полученную Квалифицированную электронную подпись (der/base64) (CAdES-BES, Cades-T (с меткой времени TSP), CAdES-X Long Type 1 (c метками TSP и OCSP))
  • подписать МЧД, размещенной в сервисе средствами сервиса
  • предоставить возможность подписания МЧД на web-форме сервиса
  • предоставить возможность подписания по ссылке Доверителя
  • предоставить возможность подписания в мобильном приложении МИГ24

Получить xml-файл доверенности - /api/m4d/{mchdInfoId}/xml

Возвращается xml-файл МЧД

Загрузка подписи sig для неподписанной доверенности - /api/import?mchdInfoId={mchdInfoId}&idFileDate={idFileDate}
mchdInfoId - идентификатор МЧД в сервисе
idFileDate - дата реального подписания xml МЧД на стороне пользователя. Указывается, если отличается от текущей даты.
Важно: при приеме sig в этом методе сервис сформирует xml из актуальных данных этой МЧД на указанную дату и произведет проверку соответствия подписанных данных и данных в сервисе.


Подписание МЧД, размещенной в реестре сервиса - /api/signature/
Процесс подписание одинаков для всех типов МЧД сервиса, включая СФР.
Шаг 1 - Предоставление сертификата КЭП подписанта, запрос хеша xml МЧД для подписания /api/signature/step1 пример
Шаг 2 - Подписание полученного хеша xml МЧД на стороне внешней ИС, отправка подписанного хеша xml МЧД, получение хеша pdf (электронная МЧД) для подписания /api/signature/step2 пример
Шаг 3 - Подписание полученного хеша pdf МЧД на стороне внешней ИС, отправка подписанного хеша pdf МЧД, завершение подписания - /api/signature/step3 пример

Создание ссылки на подписание МЧД на web форме сервиса
Ссылка имеет вид https://m4d.mig24.online/m4d/ + идентификатор МЧД - mchdInfoId

Создание ссылки на подписание Доверителем - /api/signature/url/{mchdInfoId}
Возвращается ссылка вида: https://mig24.online/registry/files/2e150be5-644e-48ed-a7b2-b06608bd92ce

Отправить МЧД на подписание в мобильное приложение МИГ24 - Скоро

Удалить подпись у МЧД - /api/signature/delete
Удаление пока возможно только в статусе "Ошибка при отправке на хранение"
После успешного выполнения в сервисе удаляются файлы подписи и МЧД переходит в статус " На подписании"

Отмена (отзыв) МЧД

swagger

Подписание заявления на отмену МЧД, размещенной в сервисе, можно произвести следующими способами:
  • выгрузить xml заявления на отмену, подписать своими средствами, подгрузить обратно в сервис полученную КЭП.
  • подписать xml заявления на отмену средствами сервиса
  • Скоро: получить ссылку на подписание заявление или отправить в мобильное приложение.
После подписания заявления необходимо отправить.

Сформировать и получить xml-файл отзыва подписанной доверенности -/api/revocate/{mchdInfoId}/xml

Для формирования xml необходимо предоставление дополнительных данных. пример


Загрузить подпись sig для отмены МЧД - /api/revocate/sig

mchdInfoId - идентификатор МЧД в сервисе


Подпись отмены (отзыва) МЧД:

Шаг 1 - Передача сертификата КЭП подписанта и данных для отмены, получение хеша xml файла отмены МЧД для подписания - /api/revocate/signature/step1 пример
Шаг 2 - Подписание хеш отзыва xml МЧД и отправка подписанного хеша отзыва xml МЧД - api/revocate/signature/step2пример

Отправить подписанное заявление на отмену МЧД - /api/fns/revoke/{mchdInfoId}?email={email}
email - Email для получения уведомления о результатах отмены.

Получить zip-архив с xml отмены МЧД и файла подписи - /api/revocate/{mchdInfoId}/archive
Возвращается файл

Работа с реестром МЧД сервиса

swagger

Получить список всех МЧД для пользователя - /api/mchd-infos?userId=

userId - необязательны Id пользователя, создавшего МЧД. Если userId пустой, то используется ID пользователя из авторизации


Получить список всех подписанных МЧД по СНИЛС уполномоченного лица - /api/signed/{snils}

Возвращается массив данных - метод требует отдельного разрешения для использования


Получить список всех МЧД по ОГРН (ОГРНИП) доверителя - /api/mchd-infos/ogrn/{ogrn}

Возвращается массив данных - метод требует отдельного разрешения для использования

Работа существующей МЧД

swagger

Копировать МЧД - /api/m4d/{mchdInfoId}/copy

Возвращается идентификатор mchdInfoId на новую (копию) МЧД


Удалить МЧД в сервисе- /api/m4d/{mchdInfoId}

МЧД помечается как удаленная и не показывается при просмотре. Удаление подписанной МЧД не допускается.


Проверить МЧД на правильность заполненности - /api/m4d/{mchdInfoId}/validate
Если проверка пройдена успешно, то "IsValid": true, если не успешно, то "IsValid": false
и возвращается список ошибок (json).

Сменить форму редактирования МЧД - /api/m4d/{mchdInfoId}/form-kind/{formKind}
Вид формы для единого формата: FNS, FTS
Форма редактирования влияет только на внешний вид web-формы.
Применимо только "своих" для МЧД, созданных через API.

Установить факт оплаты МЧД - /api/m4d/{mchdInfoId}/paid
Метод нужен для возможности подписания доверенности через web, не через API.
Применимо только "своих" для МЧД, созданных через API.
Возможность использования данного метода регулируется договором (платно)

Получить статус оплаты МЧД - /api/m4d/{mchdInfoId}/is-paid
Возвращает набор параметров
"IsPaid" - признак, оплачена ли МЧД
"Member" - информация, кто произвел оплату (ОГРН/СНИЛС,UserID)
"Method": метод, которым произведена оплата.
"PayInfoId": идентификатор записи об оплате

Обновить (изменить) тип системы хранения существующей МЧД - /api/m4d/update-storage-type

Изменение места хранения МЧД:

  • Fns - ЦПРР ФНС
  • Mig24 - МЧД.МИГ24

Изменение возможно только для неподписанной МЧД.


Получить информацию о файлах МЧД - /api/m4d/{mchdInfoId}/files-info

Возвращает список файлов, сформированных по данной МЧД (xml, sig, pdf)


Получить zip-архив файлов МЧД - /api/m4d/{mchdInfoId}/archive

Возвращается zip-архив файлов МЧД

Получить xml-файл МЧД - /api/m4d/{mchdInfoId}/xml

Возвращается xml-файл МЧД

Получить pdf-файл МЧД - /api/m4d/{mchdInfoId}/pdf
Возвращается pdf-файл МЧД

Отправить в ФТС запрос на регистрацию МЧД - /api/send-link-poa/{mchdInfoId}
Зарегистрировать в ФТС можно только МЧД с кодовыми полномочиями для ФТС.

Получить сокращенные мета-данные по МЧД - /api/mchd-infos/{mchdInfoId}/short
Возвращается номер МЧД, ИНН доверителя, ИНН,СНИЛС уполномоченного, статус МЧД. - метод требует отдельного разрешения для использован

Взаимодействие с ЦПРР ФНС

swagger

Отправить МЧД в ЦПРР ФНС /api/fns/send/{mchdInfoId}?validate=true

validate - с проверкой xml по xsd-схеме


Отправить подписанное заявление на отмену МЧД - /api/fns/revoke/{mchdInfoId}?email={email}

email - Email для получения уведомления о результатах отмены.


Получить информацию о статусе и сроке действия МЧД в ЦПРР ФНС - /api/fns/check/{mchdNumber}/info

Если необходимо для номера использовать символы типа "/", то используется метод - /api/fns/check/info?number={mchdNumber}

Возвращается массив сведений.
Сначала производится поиск доверенности в ЦПРР и возвращается статус из ЦПРР.
Если ЦПРР не доступен, то будет ошибка "Ошибка сервера ФНС".
Если в ЦПРР доверенность не найдена, то производится поиск в сервисе МЧД24 и возвращается статус из МЧД24.
Если в ЦПРР и МЧД24 доверенность не найдена, то возвращается ошибка "Доверенность не найдена в ЦПРР ФНС и отсутствует в сервисе МЧД24".

Получить файл архива МЧД из ЦПРР ФНС - /api/fns/download/{mchdNumber}/{issuerInn}/{representativeInn}
Необходимо указать номер МЧД, ИНН Доверителя, ИНН любого Уполномоченного.
Возвращается zip-архив доверенности.
В случае отсутствия этой МЧД на узле МИГ24 вначале будет возвращаться строка "Статус: ОПЕРАЦИЯ ВЫПОЛНЯЕТСЯ. Идет запрос данных с узла ФНС. Попробуйте скачать позднее." Ориентировочное время получения МЧД с других узлов - до 60 сек.
Пример архива с файлами МЧД

Получить информацию о полномочиях и статусе МЧД из ЦПРР ФНС

/api/fns/check-powers/{mchdNumber}/{issuerInn}
Возвращается массив сведений.
В случае отсутствия этой МЧД на узле МИГ24 вначале будет возвращаться строка "Статус: ОПЕРАЦИЯ ВЫПОЛНЯЕТСЯ. Идет запрос данных с узла ФНС. Попробуйте скачать позднее." Ориентировочное время получения МЧД с других узлов - до 60 сек.

Получить статус доверенности из ЦПРР ФНС и обновить его в списке МЧД

/api/fns/sync/{mchdInfoId}
Необходим для быстрой ручной актуализации статуса МЧД в МИГ24 из ЦПРР ФНС.

Проведение проверок использования МЧД

swagger

Проверить МЧД на правильность заполненности - /api/m4d/{mchdInfoId}/validate
Если проверка пройдена успешно, то "IsValid": true, если не успешно, то "IsValid": false
и возвращается список ошибок (json).

Проведение серии проверок на основании предоставленного набора данных -/api/m4d/special/check/perform
Перечень возможных предоставляемых данных:
  • файлы МЧД (xml+sig)
  • файлы документа (документ, sig документа)
  • номер МЧД
  • ИНН Доверителя
  • ИНН Уполномоченного
  • набор полномочий
На основании предоставленных данных, при возможности, сервис получает МЧД из соответствующей ИС Хранения, производит проверки и возвращает массив результатов:
  1. GetMchdStoragePlace - Получение информации о месте хранения
  2. GetMchdCprrStatus - Статус МЧД в ИС хранения
  3. IsMchdXsdStructureNormal - Проверка структуры МЧД по XSD
  4. IsMchdFilledValid - Проверка на корректность заполнения
  5. sMchdSignCorrespondToSelf - Соответствие ЭП МЧД самой МЧД
  6. IsMchdSignValid - Действительность КЭП МЧД (Выдана АУЦ, Действительность на момент проверки)
  7. IsMchdPrincipalEqualToMchdSigner - Соответствие доверителя из МЧД и подписанта МЧД (по ИНН, ОГРН, СНИЛС)
  8. IsMchdAttorneyEqualToDocumentSigner - Соответствие поверенного из МЧД и подписанта документа (из КЭП документа)
  9. IsMchdPrincipalEqualToDocumentSide - Соответствие доверителя из МЧД и стороны в документе
  10. IsMchdHavePowers - Наличие в МЧД запрошенного набора (кодов) полномочий (вхождение). Коды набора полномочий указываются через запятую. Если какого-то из запрошенных полномочий в МЧД нет, то это будет указано в результате
  11. sDocumentSignCorrespondToSelf - Соответствие ЭП документа самому документу
  12. IsDocumentSignValid - Действительность КЭП Документа (Выдана АУЦ, Действительность на момент проверки)
  13. IsLocalMchdEqualToOuterFile - Сверка загруженного файла МЧД и файла МЧД в ИС хранения
Красным помечены проверки, которые еще в работе