.. _`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 .. _`PATCH DataToSign`: Здесь ссылка на новый метод Отправка уведомлений в МВД ========================== С 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:`POST Upload`. 4. Создайте документ в черновике :ref:`POST Add Document`. В теле запроса передайте идентификатор загруженного контента ``content-id``. 5. Проверьте черновик перед отправкой: :ref:`POST Check`. Без проверки черновик нельзя отредактировать для отправки в МВД. 6. Подготовьте черновик для добавления подписи: :ref:`PATCH DataToSign`. * API Контур.Экстерн добавит в черновик идентификатор уведомления — ``OrderId``. Черновик нельзя менять после добавления идентификатора, а случае изменений, повторно отправить запрос на подготовку черновика. 7. Добавьте подпись в черновик уведомления: :ref:`POST Add Signature`. 8. Запустите последовательность методов, когда черновик будет готов к отправке: :ref:`POST Check` -> :ref:`POST Prepare` -> :ref:`POST Send`. a. Укажите флаг deferred = true для отложенного выполнения задач. b. Каждый из методов возвращает task-id для отслеживания выполнения задачи. 9. Проверяйте результат выполнения задачи: :ref:`GET DraftTask`. Запрашивайте результат, пока статус не станет Success. Получение статуса уведомления ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Получите статус уведомления: :ref:`GET Docflow`. 1. Положительный результат: уведомление принято. Обновите информацию в своей информационной системе. 2. Отрицательный результат: 1. Детализированный отказ. Уведомление не принято. Обновите информацию в своей информационной системе и подайте уведомление повторно с учетом исправления причин отказа. 2. Недетализированный отказ. Уведомление не принято. .. note:: Как получить детализированный отказ: 1. Повторно получите действующий токен :ref:`POST Gosuslugi Auth` на сотрудника организации. 2. Получите повторно статус уведомления: :ref:`GET Docflow`.