.. _`16.05.2024 N 260`: https://normativ.kontur.ru/document?moduleId=1&documentId=472735 .. _`по инструкции`: https://support.kontur.ru/extern/51677-nastrojka_otpravki_uvedomlenij_v_mvd_po_api .. _`POST Gosuslugi Auth`: https://developer.kontur.ru/doc/extern/method?type=post&path=/v1/%7BaccountId%7D/organizations/%7BorgId%7D/gosuslugi-auth Отправка уведомлений в МВД ========================== С 23 июня 2024 года работодатели должны уведомлять МВД в течение трех рабочих дней о заключении или расторжении договоров с иностранцами, а также при выплате зарплаты высококвалифицированным иностранным специалистам раз в квартал. Приказ МВД РФ от `16.05.2024 N 260`_. Через API Контур.Экстерн можно отправить следующие формы уведомлений: * Уведомление о приеме на работу иностранного сотрудника. * Уведомление об увольнении иностранного сотрудника. * Уведомление о выплатах высококвалифицированных специалистов (ВКС). Что нужно для отправки уведомлений ---------------------------------- Руководителю организации нужно создать личный кабинет организации на Госуслугах, чтобы отчитываться в МВД по иностранцам и ВКС. Далее руководитель должен добавить ответственного сотрудника за работу и выдать ему доверенность, а также выбрать систему для документооборота — Контур.МВД. Сотрудник со свой стороны должен подтвердить добавление себя как сотрудника в личном кабинете организации на Госуслугах. Контролирующий орган присвоит ему личный идентификатор — API-ключ на Госуслугах состоящий из 32 символов. Этот API-ключ нужен для получения токена, чтобы API Контур.Экстерн мог использовать его при работе с уведомлениями. Настроить организацию и добавить сотрудника можно `по инструкции`_. Как происходит взаимодействие ----------------------------- .. image:: /_static/mvd-notification-schema.png Интеграционный модуль должен запросить токен для авторизации на ответственного сотрудника с помощью метода :ref:`POST Gosuslugi Auth`. Он нужен для подготовки черновика, его отправки и получения детализированного результата. Токен (Access Token) — идентификатор с коротким периодом времени действия для авторизации сотрудника на Госуслугах. API Контур.Экстерн сохраняет токен себе и периодически обновляет его, пока действителен файл подписи. Файл подписи — это файл в формате PKCS#7 с расширением .p7s, который нужно создать путем подписания API-ключа сотрудника. Может быть сформирован только сертификатом с ИНН организации, на сотрудника которой выдан API-ключ. Для работы с методом авторизации нужно перевести файл в формат base64. API Госуслуг определяет срок жизни подписи к API-ключу — 18 часов, а потому нужно периодически указывать новый файл подписи в параметрах к методу. В интеграции важно учесть периодичность запросов к методу для авторизации с Госуслугами. После создания черновика нужно подготовить его для отправки в МВД. Для этого был добавлен метод :ref:`PATCH DataToSign`, который добавляет в черновик идентификатор уведомления — OrderId. Черновик нельзя менять после добавления идентификатора, а случае изменений, повторно отправить запрос на подготовку черновика. Подробнее на странице Алгоритм работы с методами API. Как работать с результатами приема ---------------------------------- После приема уведомления МВД возвращает результат: положительный или отрицательный. Документ ``urn:document:mvd-notification-epgu-protocol`` всегда есть для положительного результата и детализированного отрицательного результата. * Положительный результат — уведомление принято. Документ можно получить с любого действующего или истекшего токена среди добавленных сотрудников организации. * Отрицательный результат — уведомление не принято. Результат бывает двух видов: * Детализированный отказ в приеме уведомления. Можно получить с действующего токена сотрудника, который отправил уведомление. * Недетализированный отказ в приеме уведомления. Не содержит в документообороте документа ``urn:document:mvd-notification-epgu-protocol``. Для получения детализированного отказа обновите токен сотрудника, который отправил уведомление. После этого отправьте повторный запрос на получение результата обработки уведомления. Алгоритм работы с методами API ------------------------------ Отправка уведомления ~~~~~~~~~~~~~~~~~~~~ 1. Получите токен: :ref:`POST Gosuslugi Auth`. Укажите в теле запроса: 1. ``gosuslugi-uid`` — API-ключ сотрудника из Госуслуг. 2. ``base64-signature-content`` — файл подписи API-ключа в формате base64. a. Создайте файл с расширением .txt в формате UTF-8 без BOM. Например, api_key.txt b. Скопируйте в файл API-ключ сотрудника и сохраните его. c. Выполните подписание для создания открепленной подписи в формате PKCS#7 с расширением .p7s. Сертификат для подписания должен включать ИНН организации, на сотрудника которой выдан API-ключ. d. Сконвертируйте полученный файл подписи в формат base64 и укажите его в теле запроса. Срок жизни файла подписи после отправки запроса составляет 18 часов. 2. Создайте черновик: :ref:`POST Create Draft`. При создании черновика в теле запроса обязательно укажите: * в ``recipient`` параметр ``mvd-code`` – укажите код отделения МВД для отправки уведомления в МВД. Список кодов: :ref:`GET ControlUnits`. * сведения по сотруднику из справочников МВД: :ref:`GET Handbooks`. 3. Укажите в уведомлении сведения по сотруднику из справочников МВД: :ref:`GET Handbooks`. 4. Загрузите в сервис контентов подписанный файл уведомления: :ref:`POST Upload`. 5. Создайте документ в черновике :ref:`POST Add Document`. В теле запроса передайте идентификатор загруженного контента ``content-id``. 6. Проверьте черновик перед отправкой: :ref:`POST Check`. Без проверки черновик нельзя отредактировать для отправки в МВД. 7. Подготовьте черновик для добавления подписи: :ref:`PATCH DataToSign`. * API Контур.Экстерн добавит в черновик идентификатор уведомления — ``OrderId`` и вернет идентификатор контента для подписания ``DecryptedContentId``. Черновик нельзя менять после добавления ``OrderId``, а случае изменений, нужно повторно отправить запрос на подготовку черновика. 8. Получите контент для подписания :ref:`GET Download`. В запросе укажите идентификатор контента для подписания из предыдущего шага. 9. Добавьте подпись в черновик уведомления: :ref:`POST Add Signature`. 10. Запустите последовательность методов, когда черновик будет готов к отправке: :ref:`POST Check` -> :ref:`POST Prepare` -> :ref:`POST Send`. a. Укажите флаг deferred = true для отложенного выполнения задач. b. Каждый из методов возвращает task-id для отслеживания выполнения задачи. 11. Проверяйте результат выполнения задачи: :ref:`GET DraftTask`. Запрашивайте результат, пока статус не станет Success. Получение статуса уведомления ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Получите статус уведомления: :ref:`GET Docflow`. 1. Положительный результат: уведомление принято. Обновите информацию в своей информационной системе. 2. Отрицательный результат: 1. Детализированный отказ. Уведомление не принято. Обновите информацию в своей информационной системе и подайте уведомление повторно с учетом исправления причин отказа. 2. Недетализированный отказ. Уведомление не принято. .. note:: Как получить детализированный отказ: 1. Повторно получите действующий токен :ref:`POST Gosuslugi Auth` на сотрудника организации. 2. Получите повторно статус уведомления: :ref:`GET Docflow`. Тестирование интеграции ~~~~~~~~~~~~~~~~~~~~~~~ При тестировании интеграционного модуля следует повторить действия по первичной настройке организации и добавлению сотрудника на Госуслугах в тестовой среде, включая работу с порталом, сертификатом и API-ключами. 1. Зарегистрируйте организацию на тестовом портале Госуслуг. 1. Перейдите на тестовой портал Госуслуг: https://esia-portal1.test.gosuslugi.ru/login 2. Выполните регистрацию юридического лица в тестовой среде. 2. Получите тестовой сертификат от Минцифры на руководителя организации на тестовом портале Госуслуг. 3. Получите API-ключ на сотрудника и оформите доверенность на техническом портале Госуслуг `по инструкции`_. 1. Перейдите на технический портал Госуслуг: https://svcdev-partners.test.gosuslugi.ru 2. Получите API-ключ для сотрудника, от имени которого будут выполняться запросы. 3. Выдайте сотруднику доверенность на выполнение действий от имени организации. 4. Сообщите ОГРН организации в техническую поддержку Контура для назначения полномочий для отправки уведомлений в тестовой среде. 5. Выполните отправку уведомления по алгоритму выше. На этапе создания черновика укажите специальную инспекцию МВД для проверки сценариев: * 020-016 — Результат зависит от отправляемых данных. Прямое тестирование с API Госуслуг. Описанные ниже коды используют эмулятор. * 020-017 — Неизвестный результат: уведомление отправлено, но ответ не получен. * 770-077 — Отрицательный результат: отказ с причиной. * 770-066 — Отрицательный результат: отказ без причины. * 770-001 — Отрицательный результат: отказ причины причины несколько раз подряд. * 660-066 — Положительный результат: уведомление принято.