Marketplace.GetProductItemByGuid.v1.0

Материал из Справочная система Россельхознадзора
Перейти к навигации Перейти к поиску

Marketplace:GetProductItemByGuid:v1.0

Общие сведения

Операция GetProductItemByGuid предназначена для проверки одной конкретной карточки номенклатуры (товара) во ФГИС «ВетИС» по её глобальному идентификатору.

Возвращает одну последнюю актуальную запись номенклатуры (dt:productItem: last=true, active=true):

  • наименование, артикул, GTIN;
  • иерархию «тип/продукция/вид»;
  • сведения о производителе, владельце торговой марки и площадке выпуска.

Операция выполняется в заявочном режиме через подсистему обработки заявок ApplicationManagementService профиля Marketplace.Services. Получение полного списка номенклатуры хозяйствующего субъекта профилем не предоставляется. Работа с операцией — это два обращения к сервису: сначала подаётся заявка (операция submitApplication), затем по её идентификатору получается результат (операция receiveApplicationResult). Схема описана в профиле Marketplace:Services:v1.0.

Код операции Описание операции
AMS.MPLC.1.2 Проверка зарегистрированной номенклатуры товара (карточки продукции) во ФГИС «ВетИС»

Сценарии

  • Проверка карточки товара по guid — маркетплейс передаёт глобальный идентификатор номенклатуры ВетИС. Это единственный поисковый ключ операции.

Спецификация запроса

Заявка, подаваемая операцией submitApplication, состоит из двух частей:

  • стандартные поля ВетИС.API;
  • параметры операции — передаются в поле apl:data.

Таблица описывает всю структуру заявки.

Обозначения в колонке «Название XML-элемента»:

  • точки показывают уровень вложенности;
  • <элемент> (синий) — открывающий тег;
  • </элемент> (фиолетовый) — закрывающий тег;
  • элемент без дочерних элементов показан в одной строке: <элемент></элемент>.
# Название XML-элемента Тип Обязат. Описание (нажмите [...] для отображения дополнительного описания)
001 <def:submitApplicationRequest> def:submitApplicationRequest [1..1] Заявка в единой заявочной системе на выполнение определенной операции, определяет пользователя, который инициирует запрос и содержит сведения самого запроса.
···<def:apiKey> apl:APIKey [1..1] Ключ доступа API клиентской системы маркетплейса.
···<apl:application> apl:Application [1..1] Заявка.
······<apl:serviceId> xs:Name [1..1] Код сервиса профиля — marketplace.service:1.0. Общий для всех маркетплейсов.
······<apl:issuerId> bs:UUID [1..1] Идентификатор (GUID) хозяйствующего субъекта — маркетплейса.
······<apl:data> apl:ApplicationDataWrapper [1..1] Содержимое заявки: корневой элемент запроса операции.
·········<mplc:getProductItemByGuidRequest> mplc:GetProductItemByGuidRequest [1..1] Проверка зарегистрированной номенклатуры товара.
············<mplc:localTransactionId> bs:Identifier [1..1] Идентификатор заявки в клиентской системе.
············<mplc:initiator> vd:User [1..1]
···············<vd:login> xs:NCName [1..1]

Логин пользователя ФГИС «ВетИС». Зарегистрированное полномочное лицо, от имени которого выполняется запрос.

  • Логин клиентской системы на транспортном уровне не используется как initiator.
············</mplc:initiator>
············<mplc:sessionToken> dt:OTPToken [0..1] Токен одноразового пароля (опционально).
············<bs:guid> bs:UUID [1..1] Глобальный идентификатор номенклатуры — единственный поисковый ключ операции.
·········</mplc:getProductItemByGuidRequest>
······</apl:data>
···</apl:application>
</def:submitApplicationRequest>

Правила формирования запроса:

  • Запрос выполняется только по guid карточки номенклатуры — это единственный поисковый параметр, и в схеме запроса он обязателен (1..1); без guid запрос отклоняется.
  • Операция возвращает одну запись — последнюю актуальную карточку номенклатуры (last=true, active=true); пагинация отсутствует.

Спецификация ответа

Ответ на receiveApplicationResult — та же структура заявки ВетИС.API:

  • статус обработки — в поле apl:status;
  • результат операции — в поле apl:result.

Элемент результата — mplc:getProductItemByGuidResponse, внутри него — dt:productItem. Таблица описывает всю структуру ответа.

# Название XML-элемента Тип Обязат. Описание (нажмите [...] для отображения дополнительного описания)
001 <apl:application> apl:Application [1..1] Сведения о заявке.
···<apl:applicationId> bs:UUID [0..1] Идентификатор заявки, присвоенный при подаче заявки (submitApplication).
···<apl:status> apl:ApplicationStatus [0..1] Статус заявки: ACCEPTED — принята; IN_PROCESS — обрабатывается; COMPLETED — результат в apl:result; REJECTED — отклонена, ошибки в apl:errors.
···<apl:issueDate> xs:dateTime [0..1] Дата принятия заявки.
···<apl:rcvDate> xs:dateTime [0..1] Дата получения результата.
···<apl:prdcRsltDate> xs:dateTime [0..1] Дата формирования результата.
···<apl:data> apl:ApplicationDataWrapper [0..1] Содержимое заявки (при наличии).
···<apl:result> apl:ApplicationResultWrapper [0..1] Результат бизнес-операции — при status=COMPLETED содержит корневой элемент ответа операции.
······<mplc:getProductItemByGuidResponse> mplc:GetProductItemByGuidResponse [1..1] Сведения о зарегистрированной номенклатуре товара.
002 ·········<dt:productItem> dt:ProductItem [1..1] Сведения о наименовании продукции (номенклатуре)
003 ············<bs:uuid></bs:uuid> bs:UUID [1..1] Идентификатор версии записи
004 ············<bs:guid></bs:guid> bs:UUID [1..1] Глобальный идентификатор записи
005 ············<bs:active></bs:active> xs:boolean [1..1]

Флаг активности записи

true - запись активна;

false - запись не активна.
006 ············<bs:last></bs:last> xs:boolean [1..1]

Флаг, указывающий на то, что запись является последней в истории

true - да;

false - нет.
007 ············<bs:status></bs:status> bs:VersionStatus [1..1] Статус записи
008 ············<bs:createDate></bs:createDate> xs:DateTime [1..1] Дата создания записи
009 ············<bs:updateDate></bs:updateDate> xs:DateTime [1..1] Дата последнего изменения записи
010 ············<bs:previous></bs:previous> bs:UUID [0..1] Идентификатор предыдущей версии записи
011 ············<dt:globalID></dt:globalID> dt:GTINType [0..1]

Trade Identification Number (GTIN)

идентификационный номер продукции производителя
012 ············<dt:name></dt:name> bs:String255 [0..1] Наименование номенклатуры
013 ············<dt:code></dt:code> bs:String255 [0..1]

Артикул

код продукции в соответствии с внутренним кодификатором производителя
014 ············<dt:productType></dt:productType> dt:ProductType [1..1]

Тип продукции

первый уровень иерархического справочника продукции ФГИС «ВетИС»
015 ············<dt:product> dt:Product [1..1]

Продукция

второй уровень иерархического справочника продукции ФГИС «ВетИС»
016 ···············<bs:uuid></bs:uuid> bs:UUID [1..1] Идентификатор версии записи
017 ···············<bs:guid></bs:guid> bs:UUID [1..1] Глобальный идентификатор записи
018 ···············<dt:name></dt:name> bs:String255 [1..1] Наименование продукции
019 ···············<dt:code></dt:code> bs:String255 [0..1] Код ТН ВЭД
020 ············</dt:product>
021 ············<dt:subProduct> dt:SubProduct [1..1]

Вид продукции

третий уровень иерархического справочника продукции ФГИС «ВетИС»
022 ···············<bs:uuid></bs:uuid> bs:UUID [1..1] Идентификатор версии записи
023 ···············<bs:guid></bs:guid> bs:UUID [1..1] Глобальный идентификатор записи
024 ···············<dt:name></dt:name> bs:String255 [1..1] Наименование вида продукции
025 ···············<dt:code></dt:code> bs:String255 [0..1] Код ТН ВЭД
026 ············</dt:subProduct>
027 ············<dt:correspondsToGost></dt:correspondsToGost> xs:boolean [1..1] Соответствие ГОСТ
028 ············<dt:gost></dt:gost> bs:String255 [0..1] ГОСТ
029 ············<dt:producer> dt:BusinessEntity [0..1] Хозяйствующий субъект (ХС) производитель продукции
030 ···············<bs:uuid></bs:uuid> bs:UUID [1..1] Идентификатор версии ХС
031 ···············<bs:guid></bs:guid> bs:UUID [1..1] Глобальный идентификатор ХС
032 ···············<dt:fullName></dt:fullName> bs:String255 [0..1] Наименование ХС
033 ···············<dt:fio></dt:fio> bs:String255 [0..1] ФИО ХС
034 ············</dt:producer>
035 ············<dt:tmOwner> dt:BusinessEntity [0..1] ХС-собственник торговой марки
036 ···············<bs:uuid></bs:uuid> bs:UUID [1..1] Идентификатор версии ХС
037 ···············<bs:guid></bs:guid> bs:UUID [1..1] Глобальный идентификатор ХС
038 ···············<dt:fullName></dt:fullName> bs:String255 [0..1] Наименование ХС
039 ···············<dt:fio></dt:fio> bs:String255 [0..1] ФИО ХС
040 ············</dt:tmOwner>
041 ············<dt:producing> dt:ProductItemProducing [0..*] Список площадок, на которых выпускается данная продукция
042 ···············<dt:location> dt:Enterprise [1..1] Площадка, осуществляющая выпуск продукции
043 ··················<bs:uuid></bs:uuid> bs:UUID [1..1] Идентификатор версии площадки
044 ··················<bs:guid></bs:guid> bs:UUID [1..1] Глобальный идентификатор площадки
045 ··················<dt:name></dt:name> bs:String255 [1..1] Наименование площадки
046 ···············</dt:location>
047 ············</dt:producing>
048 ············<dt:packaging> dt:Packaging [0..1] Фасовка
049 ···············<dt:packagingType> dt:PackingType [1..1] Тип упаковки
050 ··················<bs:uuid></bs:uuid> bs:UUID [1..1] Идентификатор версии типа упаковки
051 ··················<bs:guid></bs:guid> bs:UUID [1..1] Глобальный идентификатор упаковки
052 ··················<dt:globalID></dt:globalID> dt:PackingCodeType [1..1] Уникальный идентификатор упаковки
053 ··················<dt:name></dt:name> bs:String255 [1..1] Наименование упаковки
054 ···············</dt:packagingType>
055 ···············<dt:quantity></dt:quantity> xs:integer [0..1] Количество единиц упаковки
056 ···············<dt:volume></dt:volume> bs:Decimal [0..1] Объём единицы упаковки товара
057 ···············<dt:unit> dt:Unit [0..1] Единица измерения объёма единицы упаковки товара
058 ··················<bs:uuid></bs:uuid> bs:UUID [1..1] Идентификатор версии единицы измерения
059 ··················<bs:guid></bs:guid> bs:UUID [1..1] Глобальный идентификатор единицы измерения
060 ··················<dt:name></dt:name> bs:String255 [1..1] Наименование единицы измерения
061 ···············</dt:unit>
062 ············</dt:packaging>
063 ············<dt:additionalCharacteristics> dt:ProductItemCharacterictics [0..1] Дополнительные характеристики продукции
064 ···············<dt:classification> dt:ClassificationAttribute [0..1] Классификация продукции
065 ··················<dt:attrCode>PRODUCT_CATEGORY></dt:attrCode>PRODUCT_CATEGORY> dt:CodeType [1..1] Код атрибута - Категория продукции
066 ··················<dt:attrName>Категория продукции></dt:attrName>Категория продукции> bs:Ntext [1..1] Наименование атрибута
067 ··················<dt:classCode></dt:classCode> dt:CodeType [1..1]

Код значения атрибута "Категория продукции"

Возможные значения: UNDEFINED - категория не определена UNCLASSIFIED – не классифицировано RAW – сырец, исходное сырьё INTERMEDIATE – полуфабрикат

CONSUMER_PACKAGED – готовая продукция (в потреб. упаковке)
068 ··················<dt:className></dt:className> bs:Text [1..1]

Наименование значения атрибута

Текстовое представление значения classCode: Категория не определена Не классифицировано Сырец, исходное сырьё Полуфабрикат

Готовая продукция (в потребительской упаковке)
069 ···············</dt:classification>
070 ···············<dt:classification> dt:ClassificationAttribute [0..1] Классификация продукции
071 ··················<dt:attrCode>INTENDED_USE></dt:attrCode>INTENDED_USE> dt:CodeType [1..1] Код атрибута - Предназначение партии подконтрольной продукции
072 ··················<dt:attrName>Предназначение партии подконтрольной продукции></dt:attrName>Предназначение партии подконтрольной продукции> bs:Ntext [1..1] Наименование атрибута
073 ··················<dt:classCode></dt:classCode> dt:CodeType [1..1]

Код значения атрибута "Предназначение партии подконтрольной продукции"

Возможные значения: HUMAN_CONSUMPTION - в пищу людям MANUFACTURING_HUMAN_CONSUMPTION - для переработки с целью получения подконтрольных товаров, предназначенных в пищу людям DECONTAMINATION_HUMAN_CONSUMPTION - для переработки с обеззараживанием с целью получения подконтрольных товаров, предназначенных в пищу людям ANIMAL_FEED - в корм животным MANUFACTURING_ANIMAL_FEED - для переработки с целью получения подконтрольных товаров, предназначенных в корм животным MEDICAL_USE - для медицинских целей MANUFACTURING_MEDICAL_USE - для переработки с целью получения подконтрольных товаров, предназначенных для медицинских целей SCIENTIFIC_PURPOSES - для биологических, ветеринарных и биотехнологических целей MANUFACTURING_SCIENTIFIC_PURPOSES - для переработки с целью получения подконтрольных товаров, предназначенных для биологических, ветеринарных и биотехнологических целей LABORATORY_TESTS - для диагностических и иных лабораторных исследований TECHNICAL_PURPOSES - для технических целей DISPOSAL - для утилизации DESTRUCTION - для уничтожения

EXAMINATION - для проведения ветеринарно-санитарной экспертизы
074 ··················<dt:className></dt:className> bs:Text [1..1]

Наименование значения атрибута

Текстовое представление значения classCode: В пищу людям Для переработки с целью получения подконтрольных товаров, предназначенных в пищу людям Для переработки с обеззараживанием с целью получения подконтрольных товаров, предназначенных в пищу людям В корм животным Для переработки с целью получения подконтрольных товаров, предназначенных в корм животным Для медицинских целей Для переработки с целью получения подконтрольных товаров, предназначенных для медицинских целей Для биологических, ветеринарных и биотехнологических целей Для переработки с целью получения подконтрольных товаров, предназначенных для биологических, ветеринарных и биотехнологических целей Для диагностических и иных лабораторных исследований Для технических целей Для утилизации Для уничтожения

Для проведения ветеринарно-санитарной экспертизы
075 ···············</dt:classification>
076 ···············<dt:attribute> dt:MeasuredAttribute [0..1] Дополнительный атрибут продукции
077 ··················<dt:attrCode>MILK_FAT_MASS_FRACTION></dt:attrCode>MILK_FAT_MASS_FRACTION> dt:CodeType [1..1] Код атрибута - Массовая доля жира
078 ··················<dt:attrName>Массовая доля жира></dt:attrName>Массовая доля жира> bs:Ntext [1..1] Наименование атрибута
079 ··················<dt:attrValue> dt:ComplexMeasure [1..1]

Значение атрибута

Значение атрибута должно быть задано одним из следующих способов: указано value - точное значение атрибута указано minValue и maxValue - интервал значений атрибута указано minValue - нижнее предельное значение (не ниже)

указано maxValue - верхнее предельное значение (не выше)
080 ·····················<dt:value></dt:value> bs:Decimal [0..1]

Точное значение (%)

точность до 3-х знаков после запятой
081 ·····················<dt:minValue></dt:minValue> bs:Decimal [0..1]

Минимальное значение (%)

точность до 3-х знаков после запятой
082 ·····················<dt:maxValue></dt:maxValue> bs:Decimal [0..1]

Максимальное значение (%)

точность до 3-х знаков после запятой
083 ··················</dt:attrValue>
084 ···············</dt:attribute>
085 ···············<dt:attribute> dt:MeasuredAttribute [0..1] Дополнительный атрибут продукции
086 ··················<dt:attrCode>MILK_PROTEIN_MASS_FRACTION></dt:attrCode>MILK_PROTEIN_MASS_FRACTION> dt:CodeType [1..1] Код атрибута - Массовая доля белка
087 ··················<dt:attrName>Массовая доля белка></dt:attrName>Массовая доля белка> bs:Ntext [1..1] Наименование атрибута
088 ··················<dt:attrValue> dt:ComplexMeasure [1..1]

Значение атрибута

Значение атрибута должно быть задано одним из следующих способов: указано value - точное значение атрибута указано minValue и maxValue - интервал значений атрибута указано minValue - нижнее предельное значение (не ниже)

указано maxValue - верхнее предельное значение (не выше)
089 ·····················<dt:value></dt:value> bs:Decimal [0..1]

Точное значение (%)

точность до 3-х знаков после запятой
090 ·····················<dt:minValue></dt:minValue> bs:Decimal [0..1]

Минимальное значение (%)

точность до 3-х знаков после запятой
091 ·····················<dt:maxValue></dt:maxValue> bs:Decimal [0..1]

Максимальное значение (%)

точность до 3-х знаков после запятой
092 ··················</dt:attrValue>
093 ···············</dt:attribute>
094 ···············<dt:attribute> dt:MeasuredAttribute [0..1] Дополнительный атрибут продукции
095 ··················<dt:attrCode>DENSITY></dt:attrCode>DENSITY> dt:CodeType [1..1] Код атрибута - Плотность
096 ··················<dt:attrName>Плотность></dt:attrName>Плотность> bs:Ntext [1..1] Наименование атрибута
097 ··················<dt:attrValue> dt:ComplexMeasure [1..1]

Значение атрибута

Значение атрибута должно быть задано одним из следующих способов: указано value - точное значение атрибута

указано minValue и maxValue - интервал значений атрибута
098 ·····················<dt:value></dt:value> bs:Decimal [0..1]

Точное значение (г/см3)

точность до 3-х знаков после запятой
099 ·····················<dt:minValue></dt:minValue> bs:Decimal [0..1]

Минимальное значение (г/см3)

точность до 3-х знаков после запятой
100 ·····················<dt:maxValue></dt:maxValue> bs:Decimal [0..1]

Максимальное значение (г/см3)

точность до 3-х знаков после запятой
101 ··················</dt:attrValue>
102 ···············</dt:attribute>
103 ············</dt:additionalCharacteristics>
104 ·········</dt:productItem>
······</mplc:getProductItemByGuidResponse>
···</apl:result>
···<apl:errors> apl:BusinessErrorList [0..1]
······<apl:error> apl:BusinessError [0..*] Ошибка — при status=REJECTED. Строковый текст сообщения с атрибутом code (код ошибки, обязательный) и необязательным атрибутом qualifier.
···</apl:errors>
</apl:application>

Примеры запроса / ответа

Запрос (submitApplication): 

<def:submitApplicationRequest xmlns:def="http://api.vetrf.ru/schema/cdm/application/ws-definitions"
                              xmlns:apl="http://api.vetrf.ru/schema/cdm/application"
                              xmlns:mplc="http://api.vetrf.ru/schema/cdm/marketplace/applications/v1"
                              xmlns:bs="http://api.vetrf.ru/schema/cdm/base"
                              xmlns:vd="http://api.vetrf.ru/schema/cdm/mercury/vet-document/v2"
                              xmlns:dt="http://api.vetrf.ru/schema/cdm/dictionary/v2">
  <def:apiKey>APIKEY_EXAMPLE</def:apiKey>
  <apl:application>
    <apl:serviceId>marketplace.service:1.0</apl:serviceId>
    <apl:issuerId>8f14e45f-ceea-467f-a9f2-d5e1a0b3c4d5</apl:issuerId>
    <apl:data>
      <mplc:getProductItemByGuidRequest>
        <mplc:localTransactionId>MP-20261001-000234</mplc:localTransactionId>
        <mplc:initiator><vd:login>marketplace.user01</vd:login></mplc:initiator>
        <bs:guid>6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d</bs:guid>
      </mplc:getProductItemByGuidRequest>
    </apl:data>
  </apl:application>
</def:submitApplicationRequest>

Ответ на submitApplication — apl:application с присвоенным applicationId и статусом ACCEPTED.

Ответ на receiveApplicationResult — фрагмент apl:result: 

<mplc:getProductItemByGuidResponse>
  <dt:productItem>
    <bs:uuid>…</bs:uuid>
    <bs:guid>6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d</bs:guid>
    <bs:last>true</bs:last>
    <bs:active>true</bs:active>
    <dt:globalID>4600000000013</dt:globalID>
    <dt:name>Молоко питьевое пастеризованное 3,2%</dt:name>
    <dt:productType>…</dt:productType>
    <dt:product>…</dt:product>
    <dt:subProduct>…</dt:subProduct>
    <dt:producer>
      <bs:guid>1f2e3d4c-5b6a-4f7e-8d9c-0a1b2c3d4e5f</bs:guid>
      <dt:fullName>АО «Молочный комбинат»</dt:fullName>
    </dt:producer>
  </dt:productItem>
</mplc:getProductItemByGuidResponse>

По результату операции маркетплейс сверяет продавца с участниками, указанными в карточке товара: идентификатор производителя (producer.guid) и идентификатор владельца торговой марки (tmOwner.guid) должны совпадать с guid продавца, полученным в операции CheckBusinessEntity; GTIN — со значением поля globalID возвращённой карточки.

Коды ошибок

Профиль не задаёт собственных кодов ошибок: ошибки ФГИС «ВетИС» передаются маркетплейсу без изменений. Ошибки возможны на двух этапах обработки заявки:

Этап обработки заявки Когда возникает Что получает маркетплейс
До выполнения операции В запросе не передан обязательный guid Заявка отклоняется, операция не выполняется
При выполнении операции ФГИС «ВетИС» возвращает ошибку при обработке заявки Заявка отклоняется (статус REJECTED), код и текст ошибки — в элементе apl:errors

Источник

Источник — http://help.vetrf.ru/index.php?title=Marketplace.GetProductItemByGuid.v1.0&oldid=45649