Разбор распространенных ошибок API ФГИС «Меркурий»: причины возникновения и способы устранения.
При интеграции учетных систем с API ФГИС «Меркурий» разработчики и пользователи регулярно сталкиваются с ошибками обработки запросов. Большинство из них связано с недостаточными правами доступа, некорректными данными, статусом площадок или особенностями оформления ветеринарных сопроводительных документов (ВСД).
Разобраться в причине помогает код ошибки, который возвращает API. Знание наиболее распространенных кодов позволяет значительно сократить время поиска проблемы и восстановления работы интеграции.
Как формируются коды ошибок
Большинство ошибок API ФГИС «Меркурий» имеют формат MERCXXXXX, где после префикса MERC следует пятизначный числовой идентификатор.
Например:
MERC14558;
MERC02386;
MERC13454.
Кроме цифрового кода система обычно возвращает текстовое описание ошибки, которое помогает определить источник проблемы.
Ошибки авторизации и прав доступа
1.Client — ошибка SOAP-сервера
Одна из наиболее распространенных ошибок возникает при неверной авторизации приложения.
Чаще всего причиной становится:
некорректный APIKey;
неправильные параметры подключения к сервису;
ошибки формирования SOAP-запроса.
В первую очередь рекомендуется проверить используемый APIKey и настройки подключения.
2. Ошибка аутентификации
Возникает при неверном логине или пароле пользователя ВетИС.
Следует проверить:
правильность учетных данных;
отсутствие лишних пробелов;
корректность сохраненных данных в используемой программе.
3. MERC14558
«Операция не может быть выполнена, так как у пользователя отсутствует доступ»
Ошибка означает, что пользователь не обладает необходимыми полномочиями для выполнения операции через API.
Следует проверить права пользователя в ВетИС.Паспорт. Для работы через API должны быть предоставлены соответствующие разрешения на чтение и выполнение операций.
4. MERC02386
«Роль пользователя не позволяет оформлять ВСД»
Причина ошибки — недостаточный уровень полномочий для оформления ветеринарного сопроводительного документа.
Необходимо убедиться, что пользователю назначена соответствующая роль, позволяющая выполнять данный тип операций.
5. MERC37387
«Пользователь-инициатор запроса обязателен для заполнения»
Ошибка возникает при отсутствии сведений о пользователе, от имени которого выполняется запрос.
Следует проверить корректность заполнения блока initiator и логина пользователя.
6. MERC37320
«Идентификатор пользователя обязателен для заполнения»
По сути аналогична предыдущей ошибке и свидетельствует об отсутствии обязательных сведений о пользователе в теле запроса.
Ошибки при оформлении ВСД
1.MERC13454
«Дата оформления ветеринарного сопроводительного документа не может быть больше текущей даты.»
Ошибка появляется, если при регистрации бумажного ВСД указана дата, превышающая текущую.
Следует проверить корректность заполнения даты оформления документа.
2. Хозяйствующий субъект прекратил деятельность
Если организация в реестре ФГИС «Цербер» имеет статус «Прекратил деятельность», оформление производственных и транспортных операций невозможно.
Перед оформлением документов рекомендуется проверить актуальный статус хозяйствующего субъекта.
3. Площадка исключена из реестра
При использовании производственной площадки со статусом «Исключен» (DELETED) система отклоняет запрос.
Проверить статус площадки можно через сервисы API либо в сведениях реестра ФГИС «Цербер».
Ошибки, связанные с номенклатурой
Некорректное описание продукции также может привести к отказу в обработке запроса.
Наиболее распространенные причины:
использование слишком общих названий продукции;
применение сокращений или неофициальных обозначений;
создание дублирующих товарных позиций;
отсутствие возможности однозначно идентифицировать продукцию.
Наименование товара должно соответствовать его фактическому виду и позволять однозначно определить продукцию.
Что проверить при возникновении ошибки
Если API возвращает код ошибки, рекомендуется последовательно проверить:
код и текст ошибки;
корректность логина, пароля и APIKey;
права пользователя в ВетИС.Паспорт;
статус хозяйствующего субъекта и площадки в ФГИС «Цербер»;
корректность GUID организаций, площадок и продукции;
соответствие используемой версии API требованиям Россельхознадзора.
Во многих случаях проблема устраняется после исправления входных данных или настройки прав пользователя.
Где искать полный перечень ошибок
Перечень возможных кодов ошибок зависит от конкретного метода API. Для каждого сервиса Россельхознадзор публикует собственный список возможных ошибок в официальной документации ВетИС.API.
Поэтому при разработке интеграции рекомендуется использовать не только общие справочники ошибок, но и описание конкретного метода, с которым работает программное обеспечение.
В результате мы видим, что большинство ошибок API ФГИС «Меркурий» связано не со сбоями системы, а с некорректными параметрами запроса, отсутствием необходимых прав или использованием неактуальных сведений о пользователях и площадках. Регулярная проверка настроек интеграции, актуальности прав доступа и соответствия требованиям официальной документации позволяет значительно сократить количество отказов при обмене данными с государственной информационной системой.
Стоит учитывать, что универсального официального справочника всех кодов ошибок MERC не существует. Россельхознадзор публикует коды ошибок для каждого конкретного метода API отдельно. Поэтому такие ошибки, как MERC14558, MERC02386, MERC37387, MERC37320, MERC13454 и другие, следует искать в документации к соответствующим сервисам (например, MercuryG2BService, EnterpriseService и др.), где они перечислены в разделе Possible faults / Возможные ошибки.
С уважением к Вашему делу, Ника Виноградова
При подготовке статьи использовалась официальная документация Россельхознадзора и материалы по работе с ВетИС.API.
Основные источники:
Справочная система Россельхознадзора — Компонент ВетИС.API Официальное описание интеграционного шлюза, требования к подключению, версии API, порядок регистрации и рекомендации по работе.
Часто задаваемые вопросы по ВетИС.API (Россельхознадзор) Разъяснения по работе API, особенностям интеграции и эксплуатации продуктивного и тестового контуров.
Функциональная спецификация ВетИС.API (Россельхознадзор) Документ содержит описание архитектуры API, механизма авторизации, использования APIKey и требований к программным клиентам.
Официальная документация ВетИС.API по отдельным методам Именно в описании каждого метода (MercuryG2BService, EnterpriseService, DictionaryService и др.) публикуются перечни возможных кодов ошибок (MERCxxxxx) и условия их возникновения.
