API ФГИС МДЛП: Рекомендации по работе и использованию

1. Общие сведения о системе

ФГИС МДЛП (Федеральная Государственная Информационная Система «Мониторинг движения лекарственных препаратов») — это система, реализующая контроль за движением лекарственных препаратов на территории РФ. Она позволяет участникам оборота (производителям, дистрибьюторам, аптечным сетям, медицинским организациям) обмениваться данными о движении маркированных лекарственных средств через: - Личной кабинет Участника (ЛК УОТ), - Интерфейсы API, - Оператор ЦРПТ (оператор системы), - Регистраторы эмиссии/выбытия (РЭ / РВ), - Операторы фискальных данных (ОФД).

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

Участники могут взаимодействовать с ФГИС МДЛП следующими способами:

Способ	Описание
Личной кабинет Участника (ЛК УОТ)	Веб-интерфейс для ручной работы с документами, отчетами и уведомлениями.
API МДЛП	Программный интерфейс (RESTful API), предназначенный для автоматизации обмена данными между ТУС участника и системой.
Интеграция через РЭ / РВ	Используется для получения КМ и отправки информации о выбытии.
Через ОФД	Для передачи информации о продажах через онлайн-кассы.

ВАЖНО: Не рекомендуется использовать внутренние методы ЛК УОТ для интеграции — они могут быть изменены без предупреждения.

3. Общие рекомендации по интеграции с API МДЛП

3.1. Аутентификация

Для доступа к API используется токен аутентификации (УКЭП).
Срок действия токена — 10 часов, но он аннулируется, если не используется более 30 минут.
Рекомендуется повторно использовать один токен, чтобы избежать множества активных сессий.

3.2. Параллелизм и производительность

Один пользователь может иметь до 10 одновременно действующих токенов.
Для увеличения производительности рекомендуется:
Зарегистрировать несколько учетных записей.
Выполнять запросы параллельно (в разных потоках).
При многопользовательской обработке необходимо избегать дублирования операций над одними и теми же документами.

4. Лимиты API МДЛП

4.1. Общие положения

Лимиты на вызовы API привязаны к учетной записи пользователя (УКЭП) и конкретному методу.
Если лимит превышен, возвращается код ошибки 429 и сообщение с указанием текущего лимита.

Пример ответа:

{
  "error_description": "Нарушено ограничение на временной интервал между вызовами! Действующий интервал: 100 мс"
}

4.2. Рекомендации по обработке ошибки 429

После получения ошибки 429 расчет задержки начинается с момента последнего запроса.
Следует увеличивать интервал между запросами или использовать экспоненциальную выдержку (например: 100 мс → 200 мс → 400 мс и т.д.).

5. Работа с документами

5.1. Жизненный цикл документа

Отправка документа (POST /api/v1/documents/send)
Получение статуса обработки (не ранее чем через 3 секунды после отправки)
Запрос квитанции (не ранее чем через 5 секунд после изменения статуса)
Скачивание квитанции или документа

5.2. Получение списка документов

Используйте методы:
GET /api/v1/documents/income – входящие документы
GET /api/v1/documents/outcome – исходящие документы
Фильтры позволяют уточнить тип, дату, статус документа и т.д.

5.3. Статусы документов

Статус	Описание
`UPLOADING_DOCUMENT`	Документ загружается
`PROCESSING_DOCUMENT`	Документ находится в обработке
`PROCESSED`	Обработка завершена успешно
`FAILED_RESULT_READY`	Обработка завершена с ошибкой
`FAILED`	Обработка завершена с критической ошибкой

ВАЖНО: Запрашивайте квитанцию только для документов в статусах PROCESSED или FAILED_RESULT_READY.

6. Работа с группами документов

Если требуется последовательная обработка нескольких документов (например, цепочка операций), следует использовать группы документов.

6.1. Этапы работы

Отправка документов с флагом bulk_processing = true
Проверка возможности запуска группы POST /api/v1/documents/bulk/check
Запуск обработки группы POST /api/v1/documents/bulk

Если один из документов в группе обработан с ошибкой, дальнейшие документы не обрабатываются.

7. Связь между документом и уведомлением

Для связи между документом и соответствующим уведомлением используется параметр request_id: - Он указывается при отправке документа. - Возвращается в квитанции как operation_id. - Позволяет однозначно идентифицировать уведомление, полученное от другого участника.

8. Обработка большого объема данных

8.1. Рекомендации

Разделите данные на части, если количество SGTIN/SSCC превышает допустимый лимит.
Используйте асинхронные методы вместо синхронных при работе с большими объёмами.
Используйте XSD-схемы 210/220 для формирования пакетов данных.

9. Архивное хранилище и реестр приостановленных SGTIN

9.1. Архивное хранилище

SGTIN перемещаются в архив через 60 дней после достижения одного из конечных статусов (например: «Продан в розницу», «Уничтожен» и др.)

9.2. Реестр временно приостановленных SGTIN

Содержит информацию о временно выведенных из оборота препаратах.
Проверять ежедневно, особенно по новым решениям.
Поиск осуществляется по GTIN и серии.

10. Устаревшие методы и параметры

Некоторые методы и параметры были признаны устаревшими и будут удалены в будущем. Например:

Метод	Статус	Комментарий
`POST /api/v1/users/find`	Устарел	Использовать `POST /api/v1/users/filter`
`GET /api/v1/reestr/branches`	Устарел	Использовать `POST /api/v1/reestr/branches/filter`
Параметр `prod_desc_label`	Устарел	Заменить на `prod_sell_name`

Рекомендуется перейти на новые методы и параметры, чтобы избежать проблем при обновлениях системы.

11. Экранирование специальных символов

При работе с JSON-ответами API: - Символы типа " и \ экранируются. - Перед использованием данных нужно выполнить обратное экранирование.

Пример:

// До
"doc_num":"151\\702"

// После
"doc_num":"151\702"

12. Рекомендации по оптимизации

Рекомендация	Описание
Используйте фильтры	Уменьшает объем данных и ускоряет выборку.
Разбивайте большие документы	На части, чтобы не превысить лимиты.
Используйте кэширование	Сохраняйте результаты частых запросов.
Обрабатывайте ошибки корректно	Анализируйте квитанции и повторяйте отправку при необходимости.

13. Полезные ссылки и материалы

ЧестныйЗнак – официальный сайт, раздел «Лекарства» → «Документы для работы в МДЛП»
Документация по API МДЛП – содержит полное описание всех методов.
Комплекты XSD-схем – для формирования XML-документов.