При интеграции учётных систем 1С с ФГИС «Меркурий» (ВетИС.API) часто возникает задача получения детальной информации о конкретной позиции продукции. Основным идентификатором в системе является GUID. Однако на практике разработчики часто сталкиваются с ситуацией, когда запрос возвращает ошибку «В реестре РСХН не найдено подходящих наименований продукции», хотя идентификатор был взят из реального ветеринарного документа (ВСД).
В этой статье мы подробно разберем, как правильно сформировать запрос к ProductService, проанализируем структуру SOAP-сообщения и выясним, почему важно различать типы идентификаторов в иерархии справочников ВетИС.
Для взаимодействия с реестром продукции используется сервис ProductService. Если нам известен GUID конкретной номенклатурной позиции, мы должны использовать метод getProductItemByGuidRequest. Рассмотрим пример формирования тела запроса, который отправляется на адрес https://api.vetrf.ru/platform/services/2.0/ProductService.
Проанализируем структуру XML-пакета:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ws="http://api.vetrf.ru/schema/cdm/registry/ws-definitions/v2"
xmlns:bs="http://api.vetrf.ru/schema/cdm/base">
<soapenv:Header/>
<soapenv:Body>
<ws:getProductItemByGuidRequest>
<bs:guid>fedf5ad4-053c-11e1-99b4-d8d385fbc9e8</bs:guid>
</ws:getProductItemByGuidRequest>
</soapenv:Body>
</soapenv:Envelope>
В данном запросе элемент bs:guid содержит уникальный идентификатор записи. Важно понимать, что ответ системы будет зависеть от того, какой именно тип объекта скрывается за этим идентификатором. Если GUID корректен и относится к продукции, сервер вернет подробные сведения (название, производитель, ГОСТ и т.д.).
Часто при разборе входящих документов (например, через getVetDocumentChangesListRequest) разработчики ошибочно извлекают GUID не самой продукции, а связанных с ней объектов. Рассмотрим ситуацию, когда сервер возвращает ошибку code="19022" с текстом «В реестре РСХН не найдено подходящих наименований продукции».
Выясним причину этой проблемы. В структуре XML-ответа по ветеринарному документу могут присутствовать различные блоки:
productItem — содержит GUID конкретного наименования продукции (4-й уровень иерархии).package или packingType — содержит сведения об упаковке.batch — содержит идентификатор записи складского журнала.Если вы по ошибке передадите в метод getProductItemByGuid идентификатор типа упаковки (например, «Коробка»), система выдаст ошибку, так как в справочнике продукции (Product) нет записи с таким кодом. Всегда проверяйте, из какого узла XML вы извлекаете данные. Для получения информации о товаре вам нужен строго ProductItem GUID.
Для эффективной работы с API необходимо различать уровни классификации продукции, принятые в Россельхознадзоре:
1. Тип продукции (1-й уровень). Например, «Мясо и мясные продукты».
2. Вид продукции (2-й уровень). Например, «Говядина».
3. Продукция (3-й уровень). Общий тип товара, например, «Охлажденная говядина в полутушах».
4. Наименование продукции (4-й уровень, ProductItem). Конкретная позиция конкретного производителя. Например, «Говядина охлажденная, категория А, ГОСТ 31797-2012, производства ООО "Мясной комбинат"».
При работе в 1С большинство операций (оформление транспортных и производственных ВСД) требует работы именно с 4-м уровнем. Именно этот GUID позволяет системе однозначно определить характеристики товара и права доступа к нему.
Разберем дополнительные аспекты, которые помогут сделать интеграцию более надежной:
Версии API: Хотя многие примеры строятся на версии 2.0, мы рекомендуем использовать актуальную версию 2.1. В ней реализована более тесная связь с системой маркировки «Честный ЗНАК». В ответе на запрос ProductItem вы сможете увидеть привязанные коды GTIN, что значительно упрощает сопоставление номенклатуры 1С с данными «Меркурия».
Статус записи: Справочники продукции в ВетИС постоянно модерируются. Записи могут объединяться как дубли или помечаться как архивные. В этом случае при запросе по старому GUID в ответе может вернуться элемент replacedBy. Нам необходимо программно обрабатывать это поле, чтобы обновлять идентификаторы в своей базе данных на актуальные.
Синхронизация справочников: Выполнение запроса по каждому товару отдельно (синхронно) оправдано только при оперативной обработке нового документа. Если же вам нужно обновить весь справочник продукции в 1С, используйте метод getProductItemChangesList. Он позволяет получить список всех изменений в реестре за определенный период, что снижает нагрузку на сервер и ускоряет работу программы.
Единицы измерения: При получении данных через getProductItemByGuid обязательно обращайте внимание на допустимые единицы измерения (unit). В «Меркурии» жестко задано, в чем может измеряться конкретный товар (кг, шт, л). Если в 1С вы укажете единицу измерения, не входящую в список допустимых для данного ProductItem, попытка оформления ВСД закончится ошибкой валидации бизнес-правил.
Рассмотрим логику, которую следует реализовать при получении успешного ответа от сервиса. Полученные данные следует кэшировать в справочнике «Номенклатура» или в соответствующем регистре сведений интеграционного модуля (например, в «ВСД: Номенклатура ВетИС»).
Проанализируем основные поля, которые нам потребуются:
Используя комплексный подход и внимательно проверяя типы GUID, мы исключим ошибки «пустых результатов» и обеспечим корректное сопоставление данных между учетной системой 1С и реестрами ФГИС «Меркурий».