Описание методов 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
Получение тестовой КЭП http://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

!!! Актуальная версия методом API - 1.1. Для использования в заголовке добавляем: "X-Version": "1.1"

Авторизация

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

Общее

Формат ДатаВремя.
С версии методов 1.1 отображение даты-времени производится в соответствии с ГОСТ ИСО 8601-2001, расширенный формат - yyyy-MM-ddThh:mm:ss.fffzzz, пример: 2024-08-14T17:11:22.117+05:00.

Возможные варианты ответов.
200 - Запрос выполнен успешно

400 - Данные в запросе не корректны, требуются изменения в данные и новый запрос
401 – Токен доступа отсутствует или указан несуществующий
402 – Оплаченный срок доступа истек
403 – Доступ к выбранному методу запрещен
404 – Запрос не может быть выполнен (такого метода нет или нет результата для запроса с указанными значениями параметров запроса)

500, 501, 503 – Сбой в работе на стороне Сервиса. После устранения потребуется повторение запроса.

Все ответы 4ХХ (ошибки) возвращаются в структурированном виде в соответствии с https://datatracker.ietf.org/doc/html/rfc7807

Response body {
Type - Тип возникшей проблемы. Наличие префикса перед error является обозначением системы хранения, которая вернула ошибку (cprr/mig24/sfr). Если префикс отсутствует – значит ошибка сформирована самим Сервисом.
Title - Краткое описание проблемы
Status - Код состояния, созданный сервером-источником для этого
Detail - Расширенное, понятное объяснение проблемы
Instance - Ссылка на URI, идентифицирующая конкретное возникновение проблемы
Пример:{
"type": "/cprr/error/not-found",
"title": "NotFound",
"status": 404,
"detail": "Доверенность не найдена",
"instance": "/api/fns/check/info"
}

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

swagger

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

Если запрос был отклонен приложением, то пользователь получает отказ, корректирует запрос и отправляет снова.
Если запрос был принят (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 - НЕ НАЙДЕНА.
В случае ошибки обработки запроса возвращается статус SEND_TO_CPRR_ERROR с указанием в поле ErrorMessage текста ошибки на русском.

Пример архива с файлами МЧД Пример использования асинхронного способа

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

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

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

swagger

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

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

Получение последней версии справочника -/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 созданной МЧД

При создании пустой МЧД по умолчанию ИСХ - ЦПРР. При необходимости можно сменить методом - /api/m4d/update-storage-type

Создание МЧД через загрузку файлов xml и sig - /api/import?validate=true
validate - проверить xml по xsd-схеме. Пока нет поддержки проверки для единого формата, поэтому или не указывать validate или validate=false.
Если <СведСист> начинается на https://m4d.mig24.online, то ИСХ будет МИГ24
Если <СведСист> начинается на https://m4d.nalog.gov.ru или равен LKFTS или равен mchd.rzd.ru, то ИСХ будет ЦПРР.
В остальных случаях будет система хранения неизвестна.

Допускается загрузка массива файлов неподписанных МЧД в формате xml.
При загрузке подписанной МЧД возможна загрузка только одного комплекта xml + sig, при этом происходит проверка на наличие в сервисе МЧД с таким же номером (guid).
Возвращается идентификатор mchdInfoId созданной МЧД

Создание МЧД через загрузку json - /api/import/json
Возвращается идентификатор mchdInfoId созданной МЧД. Для загрузки используется модель нужного типа МЧД (B2G, B2B, Единый, СФР).
Используется SvedSystType со значениями 0 - CPRR, 1 - MIG24, 2 - SFR, 3 - Unknown
Если не передавать SvedSyst, то будет использован SvedSyst с системой хранения или ссылкой из блока Info для B2B и EMCHD.

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

Создание МЧД #ФТС через загрузку json - /api/import/json-for-fts
Возвращается идентификатор mchdInfoId созданной МЧД.
Формат всегда Единый. SvedSystType: 0 - CPRR, 1 - MIG24
Общая схема запроса, Доверитель ЮЛ+ФЛ, Доверитель ИП+ФЛ
Помимо стандартных данных для МЧД, необходимы регистрационные данные ЭД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}

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

Получить список действующих МЧД по ИНН Доверителя + ИНН Уполномоченного - /api/m4ds/issuerInn/{issuerInn}/representativeInn/{representativeInn}
Возвращается массив данных (номер МЧД, название/ИНН/ОГРН доверителя/ ФИО/ИНН уполномоченного, полномочия) - метод работает только по МЧД, загруженным или созданным пользователем API

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

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-архив файлов МЧД
Если система хранения не ЦПРР, то запрос в ЦПРР выполняться не будет.
Для системы хранения МИГ24 будет скачиваться архив с квитками МИГ24.

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

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

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

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

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

Отравить подписанную МЧД на хранение в ИСХ - /api/m4d/send/{mchdInfoId}
Отравить подписанное заявление на отмену в ИСХ - /api/m4d/revoke/{mchdInfoId}

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

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 из ЦПРР ФНС.

Взаимодействие с ИСХ МИГ24

swagger

Получить информацию о статусе и сроке действия МЧД в ИСХ МИГ24 - /api/mig24/check/info?number={mchdNumber}

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

Получить файл архива МЧД из ИСХ МИГ24 - /api/mig24/download/{mchdNumber}/{issuerInn}/{representativeInn}
Необходимо указать номер МЧД, ИНН Доверителя, ИНН любого Уполномоченного.
Возвращается zip-архив доверенности.
Пример архива с файлами МЧД

Получить информацию о полномочиях и статусе МЧД из ИСХ МИГ24

/api/mig24/check-powers/{mchdNumber}/{issuerInn}

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


Загрузка МЧД в ИСХ МИГ24:

  • /api/import <СведСист> должно начинаться с начинается на https://m4d.mig24.onlineМИГ24
  • /api/import/json Используется SvedSystType со значениями 1 - MIG24.

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

swagger

Получить статус МЧД из единого реестра сведений о МЧД в ЕСИА - /api/poa-registry/get-info
По единому номеру МЧД возвращается ее статус, срок действия, данные доверителя, СНИЛС уполномоченного, мнемоника и название сервиса хранения МЧД.

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

Проведение серии проверок на основании предоставленного набора данных -/api/m4d/special/check/perform
Только для единого формата (003)
Перечень возможных предоставляемых данных:
  • файлы МЧД (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 - Сверка загруженного файла МЧД и файла МЧД в ИС хранения
Красным помечены проверки, которые еще в работе

История изменений

swagger

1.4.5.6 - 03.10.2024
Для методов версии 1.1 добавлена поддержка ответов в структурированном виде в соответствии с https://datatracker.ietf.org/doc/html/rfc7807. Подробнее тут.

1.4.5.3 - 18.09.2024
  • Добавлено версионирование методов API. Например, вызов версии 1.1 осуществляется добавлением в заголовке: "X-Version": "1.1".
  • Для нижеуказанных методов для версии 1.1 отображение даты-времени изменено на ГОСТ ИСО 8601-2001 расширенный формат - yyyy-MM-ddThh:mm:ss.fffzzz, пример: 2024-08-14T17:11:22.117+05:00.
асинхронное получение всех ответов GET /api/responses, асинхронное получение одного ответа : GET /api/responses/{responseId}, синхронное получение статуса из ЦПРР: GET /api/fns/check/{number}/info GET /api/fns/check/info?number={number} , синхронное получение полномочий из ЦПРР: GET /api/fns/check-powers/{mchdNumber}/{issuerInn}, синхронное получение статуса из МИГ: GET /api/mig24/check/{number}/info GET /api/mig24/check/info?number={number}, синхронное получение полномочий из ЦПРР: GET /api/mig24/check-powers/{mchdNumber}/{issuerInn}, синхронное получение полномочий из файла архива по MchdFileId: GET /api/m4d/files/:mchdFileId/check-powers, получение статуса по апи ЦПРР для ФНС: GET /api/fns-storage/poar-webapp/integration/poa/{mchdNumber}/public, получение статуса по апи ЦПРР для МИГ: GET /api/mig24-storage/poar-webapp/integration/poa/{mchdNumber}/public

1.4.5.0 - 04.09.2024
  • Для квитанций о приеме на хранение в ИСХ МИГ24 скорректировано название - добавлено MIG24, например, Квит_MIG24_314e020a-576b-48a5-811e-663a03b6003b.xml
  • Подключена возможность получения классификатора полномочий СФР (POWER_СFR)
  • Отключен для общего доступа метод /api/requests/send-created
  • Добавлен метод POST /api/m4d/send/{mchdInfoId} и POST /api/m4d/revoke/{mchdInfoId} для оправки МЧД и заявления на отмену в ИСХ для конкретной МЧД сервиса.
1.4.4.9 - 28.08.2024
  • Реализован блок методов, позволяющих взаимодействовать с сервисом методами, аналогичными ЦПРР ФНС (предоставляется только по отдельному согласованию).
1.4.4.8 - 27.08.2024
  • Добавлен блок работы с МЧД в ИСХ МИГ24 (загрузка, проверка статуса, получение архива или полномочий
1.4.4.0 - 09.08.2024
  • добавлен метод возвращения массива действующих МЧД по ИНН Доверителя + ИНН Уполномоченного - /api/m4ds/issuerInn/{issuerInn}/representativeInn/{representativeInn}
1.4.3.0 - 18.07.2024
  • Запущен метод проверки (синхронный /api/poa-registry/get-info и асинхронный /api/requests requestType: GetStatus, SvedSyst - POA-REESTR) статуса МЧД в Едином реестре сведений о МЧД в ЕСИА.
  • Для api-методов получения статуса и получения полномочий изменен часовой пояс в полях со временем с ЕКБ (+05:00) на МСК (+03:00). Для секунд, добавлены тысячные, так же как приходят ответы с узла ЦПРР.
  • В апи добавлен метод создания пустой МЧД для СФР (/api/sfr). После создания возвращается идентификатор МЧД mchdInfoId.
1.4.0.0 - 20.06.2024
  • Реализована возможность подписания заявления на отмену МЧД СФР.
1.3.8.2 - 03.06.2024
  • в метод POST /api/import добавлен необязательный параметр fromDate (формат DD.MM.YYYY), по которому возможно менять дату выдачи на форме и в xml.
1.3.8.0 - 21.05.2024
  • введено обязательное использование двух ИНН при запросе файлов МЧД.
  • при получения статуса МЧД добавлены отдельные поля с датой и временем. Ранее было поле только с датой - оно сохранено как и было.

Примеры интеграций

Наиболее распространенными сценариями являются:
Проверка статуса МЧД и Получение файлов МЧД.

Синхронные методы:
По номеру МЧД производится запрос статуса (GET /api/fns/check/{mchdNumber}/info). Возвращаются данные о статусе МЧД, его дате времени, сроки действия МЧД.

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

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


Проверка статуса МЧД через подписку.

Организация получает от своего контрагента данные по МЧД (номер) и на кого эта МЧД выдана.
Добавляет эти данные в свой реестр МЧД, оформляет подписку на статус этой МЧД в Сервисе через асинхронный метод /api/requests с requestType:SubscribeStatus и тут же получает ее текущий статус и срок действия. Прописывает эти данные в своем реестре и далее при проверках статуса МЧД в подписываемых документах обращается к своему реестру.
Сервис самостоятельно следит за статусом такой МЧД и при любом его изменении отдает эту информацию с очередь ответов responses для этой Организации, которая в свою очередь, получив новую информацию, вносит изменение в свой реестр МЧД.
Снятие с подписки производится методом UnsubscribeStatus. Также подписка автоматически прекращается после получения из ЦПРР и отправки в очередь статусов "Действие прекращено", "Отказ в регистрации" или "Действие истекло".
Поставить на подписку можно даже МЧД, которая еще не размещена на хранение. Как только это произойдет Сервис подготовит соответствующий response.

Банк (синхронные запросы):

Банк в своей ИС формирует набор данных, необходимый для создания МЧД нужного формата и создает МЧД в Сервисе (/api/import/json) .
При необходимости производит корректировку сведений при помощи этого же метода, с указанием внутреннего ID этой МЧД или через web-интерфейс для этой МЧД.

В определенный момент Банк производит проверку правильности заполнения МЧД (/api/m4d/{mchdInfoId}/validate), запрашивает хml файл МЧД (/api/m4d/{mchdInfoId}/xml).
Запрашивает визуализацию МЧД в pdf (/api/m4d/{mchdInfoId}/pdf).

Далее Банк в своей внутренней системе производит подписание xml этой МЧД и подгружает полученную подпись в сервис (/api/import?mchdInfoId={mchdInfoId}&idFileDate={idFileDate}) с указанием реальной даты подписания.

Отправляет подписанную МЧД на регистрацию и хранение в ЦПРР ФНС и получает ее статус (/api/fns/send/) и (/api/fns/check/{mchdNumber}/info).

Скачивает архив с МЧД, квитанциями о принятии на хранение и визуализацию (/api/m4d/{mchdInfoId}/archive).

При необходимости отмены МЧД банк запрашивает xml заявления на отмену
(/api/revocate/{mchdInfoId}/xml), подписывает его в свой системе и подгружает подпись (/api/revocate/sig). отправляет заявление на отмену в ЦПРР (/api/fns/revoke/{mchdInfoId}).
Далее запрашивает актуальный статус МЧД (api/fns/check/{mchdNumber}/info) и при его смене на статус Действие прекращено скачивает полный архив МЧД (сама МЧД, все квитанции, подписи и актуальная визуализация) (/api/m4d/{mchdInfoId}/archive).

Ритейл:
Контрагент предоставляет Поставщику данные по МЧД своих сотрудников (номер МЧД, ИНН контрагента и ИНН физического лица - сотрудника.
Поставщик по этим данным через асинхронный запрос /api/requests с requestType = GetMchd запрашивает в Сервисе МЧД из ЦПРР ФНС.
При получении ответа со статусом READY_FOR_DOWNLOAD - ГОТОВА ДЛЯ СКАЧИВАНИЯ Поставщик производит синхронный запрос для получения отдельно списка полномочий из этой МЧД (/api/fns/check-powers/{mchdNumber}/{issuerInn}).
Если полученные полномочия подходят для дальнейшего взаимодействия, то Поставщик получает файлы МЧД (/api/m4d/files/{mchdFileId}) и далее загружает их в Сервис
- /api/import под своим токеном авторизации.
Сервис в регулярностью не реже одного раз в три часа синхронизирует статусы этих МЧД с ЦПРР ФНС.

Когда к Поставщику приходит документ от Контрагента, подписанный КЭП ФЛ, поставщик через синхронный метод делает запрос в сервис по ИНН контрагента + ИНН уполномоченного (/api/m4ds/issuerInn/{issuerInn}/representativeInn/{representativeInn}.
Сервис возвращает массив действующих МЧД из списка загруженных Поставщиком, в которых есть эти два параметра. (Для случай дополнительной перепроверки отдает номер МЧД, ИНН и название Доверителя, ИНН/СНИЛС/ФИО уполномоченного, набор полномочий). Исходя из наличия действующей МЧД Поставщик принимает решения о правомерности подписания документа со стороны Контрагента.

Интегратор:
Организация готовит данные для МЧД. Создает МЧД в сервисе (/api/import/json).
Использую уникальный идентификатор МЧД Организация на выбор:
  • создает ссылку для редактирования и подписания МЧД в web-интерфейсе сервиса (ссылка имеет вид https://m4d.mig24.online/m4d/ + идентификатор МЧД)
  • создает ссылку для подписания доверителем (/api/signature/url/{mchdInfoId}), Доверитель видит визуализацию МЧД и кнопку подписать
  • отправляет МЧД для подписания в мобильное приложение МИГ24
В случае услугу подписания оплачивает организация, то выполняется метод (/api/m4d/{mchdInfoId}/paid). Иначе Сервис предложит оплатить услугу Подписанту.

Чтобы не опрашивать постоянно Сервис, подписали ли пользователь МЧД, организация формирует асинхронный запрос (/api/requests requestType:GetStatus) и после подписания МЧД и смены статусу Сервис сообщает об этом Организации (/api/responses).
При необходимости Организация запрашивает получить сформированную подпись.

Протокол API ЦПРР ФНС

swagger

Методы этого раздела НЕ входят в базовый набор по стандартному договору!!

Для облегчения использования сервиса МЧД.МИГ24 по отдельному запросу могут быть подключены методы, позволяющие взаимодействовать с сервисом по протоколу, аналогичномe API узла ЦПРР.
Для получения такого доступа - info@mig24.ru

Поддерживается по 4 метода работы с нужной ИСХ: ЦПРР ФНС или МИГ24.
При вызове метода адрес включает
  • для ЦПРР ФНС - /api/fns-storage/,
  • для МИГ24 - /api/mig24-storage/

Загрузка МЧД в ИСХ: +/poar-webapp/integration/poa/{mchdNumber}/{issuerINN}/zip

Загрузка заявления в ИСХ: +/poar-webapp/integration/poa/revoke

Получение частичных данных по МЧД (статус): +/poar-webapp/integration/poa/{mchdNumber}/public

Получение полных данных по МЧД: +/poar-webapp/integration/poa/{mchdNumber}/{issuerINN}/zip

При загрузке МЧД в ИСХ файлы МЧД загружаются сначала в сервис МЧД.МИГ24, возвращается 200 и в тело стандартного ответа добавляется параметр "mchdInfoId": GUID - внутренний идентификатор загруженной МЧД, который позволит при необходимости обращаться к этой МЧД другими методами сервиса.

После успешной загрузки МЧД в сервис, она автоматически отравляется в нужную ИСХ.
Успешность загрузки в ИСХ проверяется получение статус "Действует" или получение архива МЧД, включающего в себя квитанции приема на хранения в ИСХ.