Marketplace.CheckBusinessEntity.v1.0

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

Marketplace:CheckBusinessEntity:v1.0

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

Операция CheckBusinessEntity предназначена для проверки регистрации хозяйствующего субъекта (продавца) во ФГИС «ВетИС» по одному из поисковых сценариев: guid, inn (с необязательным kpp) либо ogrn (ОГРН/ОГРНИП).

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

Код операции Описание операции
AMS.MPLC.1.1 Проверка регистрации хозяйствующего субъекта (продавца) во ФГИС «ВетИС»

ХС не найден или не подтверждён в реестре — не ошибка: возвращается пустой список, заявка COMPLETED.

Сценарии

  • Поиск по guid — если у маркетплейса уже есть глобальный идентификатор ХС из ВетИС.
  • Поиск по inn (с необязательным kpp) — если продавец в профиле указал ИНН; КПП — уточняющий критерий, без ИНН передавать нельзя.
  • Поиск по ogrn (ОГРН/ОГРНИП) — если у продавца есть ОГРН/ОГРНИП.

В запросе должен быть указан хотя бы один поисковый критерий (guid, inn или ogrn) — при отсутствии критериев запрос отклоняется.

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

Заявка, подаваемая операцией 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:checkBusinessEntityRequest> mplc:CheckBusinessEntityRequest [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] Токен одноразового пароля (опционально).
············<dt:businessEntity> dt:BusinessEntity [1..1] Параметры фильтрации хозяйствующего субъекта: в запросе передаётся объект ХС, поисковые поля — внутри него.
···············<bs:guid> bs:UUID [0..1] Глобальный идентификатор ХС — точный поисковый критерий.
···············<dt:inn> bs:String255 [0..1] Идентификационный номер ХС (ИНН) — точный поисковый критерий; КПП может передаваться только совместно с ИНН.
···············<dt:kpp> dt:KPPType [0..1]

Код причины постановки на учёт (КПП) — уточняющий критерий.

  • Передаётся только совместно с ИНН; при передаче без ИНН запрос отклоняется.
···············<dt:ogrn> bs:String255 [0..1] ОГРН или ОГРНИП — точный поисковый критерий.
············</dt:businessEntity>
············... (остальные поля типа dt:BusinessEntity) [0..*] Остальные поля типа dt:BusinessEntity (uuid, name, fullName, fio, juridicalAddress, passport, activityLocation, registryStatus и др.) в запросе операции не используются.
·········</mplc:checkBusinessEntityRequest>
······</apl:data>
···</apl:application>
</def:submitApplicationRequest>

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

  • В запросе должен быть указан хотя бы один поисковый критерий: guid, либо inn (вместе с inn можно передать kpp), либо ogrn. Если ни один критерий не указан — запрос отклоняется, операция не выполняется.
  • kpp без inn передавать нельзя — запрос отклоняется.

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

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

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

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

Особенности содержимого ответа:

  • Отобранные записи. В ответе — только записи со статусом registryStatus = VERIFIED (подтверждённый, включённый в реестр).
  • Юридический адрес. Элемент juridicalAddress возвращается только для юридических лиц (type=1); для физических лиц и индивидуальных предпринимателей он не возвращается.
# Название 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:checkBusinessEntityResponse> mplc:CheckBusinessEntityResponse [1..1] Сведения о результате проверки регистрации хозяйствующего субъекта.
·········<dt:businessEntityList> dt:BusinessEntityList [1..1]
············(атрибуты списка)

Атрибуты типа bs:EntityList:

  • total — всего записей, удовлетворяющих запросу;
  • offset — смещение относительно первого элемента;
  • count — количество записей в списке;
  • hasMore — признак неполноты списка (при наличии total не используется).
002 ············<dt:businessEntity> dt:BusinessEntity [0..*] Хозяйствующий субъект
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 ···············<bs:next></bs:next> bs:UUID [0..1] Идентификатор следующей версии записи
012 ···············<dt:type></dt:type> dt:BusinessEntityType [1..1]

Тип хозяйствующего субъекта

  • 1 — юридическое лицо;
  • 2 — физическое лицо;
  • 3 — индивидуальный предприниматель.
013 ···············<dt:name></dt:name> bs:String255 [0..1]

Наименование хозяйствующего субъекта

  • Возвращается только для юридических лиц; для физических лиц и индивидуальных предпринимателей поле не возвращается.
014 ···············<dt:incorporationForm> dt:IncorporationForm [1..1] Организационно-правовая форма (ОПФ)
015 ··················<bs:uuid></bs:uuid> bs:UUID [1..1] Идентификатор версии ОПФ
016 ··················<dt:name></dt:name> bs:String255 [1..1] Наименование ОПФ
017 ··················<dt:code></dt:code> bs:String255 [1..1] Код ОПФ
018 ··················<dt:shortName></dt:shortName> bs:String255 [0..1] Краткое наименование ОПФ
019 ···············</dt:incorporationForm>
020 ···············<dt:fullName></dt:fullName> bs:String255 [0..1] Полное наименование хозяйствующего субъекта
021 ···············<dt:fio></dt:fio> bs:String255 [0..1]

ФИО физического лица или индивидуального предпринимателя

  • Для юридических лиц поле не возвращается.
022 ···············<dt:inn></dt:inn> bs:String255 [0..1] ИНН хозяйствующего субъекта
023 ···············<dt:kpp></dt:kpp> bs:String255 [0..1] Код причины постановки на учёт (КПП)
024 ···············<dt:ogrn></dt:ogrn> bs:String255 [0..1]

ОГРН или ОГРНИП

  • Для индивидуального предпринимателя ОГРНИП может отсутствовать.
025 ···············<dt:juridicalAddress> dt:Address [0..1]

Юридический адрес

  • Для юридических лиц передаётся в полном составе.
  • Для физических лиц и индивидуальных предпринимателей не передаётся.
026 ··················<dt:country> dt:Country [1..1] Страна
027 ·····················<bs:uuid></bs:uuid> bs:UUID [0..1] Идентификатор версии записи
028 ·····················<bs:guid></bs:guid> bs:UUID [0..1] Глобальный идентификатор объекта
029 ·····················<dt:name></dt:name> bs:String255 [1..1] Наименование адресного объекта
030 ··················</dt:country>
031 ··················<dt:region> dt:Region [1..1] Регион
032 ·····················<bs:uuid></bs:uuid> bs:UUID [0..1] Идентификатор версии записи
033 ·····················<bs:guid></bs:guid> bs:UUID [0..1] Глобальный идентификатор объекта
034 ·····················<dt:name></dt:name> bs:String255 [1..1] Наименование адресного объекта
035 ··················</dt:region>
036 ··················<dt:district> dt:District [0..1] Район
037 ·····················<bs:uuid></bs:uuid> bs:UUID [0..1] Идентификатор версии записи
038 ·····················<bs:guid></bs:guid> bs:UUID [0..1] Глобальный идентификатор объекта
039 ·····················<dt:name></dt:name> bs:String255 [1..1] Наименование адресного объекта
040 ··················</dt:district>
041 ··················<dt:locality> dt:Locality [0..1] Населённый пункт
042 ·····················<bs:uuid></bs:uuid> bs:UUID [0..1] Идентификатор версии записи
043 ·····················<bs:guid></bs:guid> bs:UUID [0..1] Глобальный идентификатор объекта
044 ·····················<dt:name></dt:name> bs:String255 [1..1] Наименование адресного объекта
045 ··················</dt:locality>
046 ··················<dt:subLocality> dt:Locality [0..1] Подчинённый населённый пункт
047 ·····················<bs:uuid></bs:uuid> bs:UUID [0..1] Идентификатор версии записи
048 ·····················<bs:guid></bs:guid> bs:UUID [0..1] Глобальный идентификатор объекта
049 ·····················<dt:name></dt:name> bs:String255 [1..1] Наименование адресного объекта
050 ··················</dt:subLocality>
051 ··················<dt:cityArea> dt:Locality [0..1] Элемент планировочной структуры
052 ·····················<bs:uuid></bs:uuid> bs:UUID [0..1] Идентификатор версии записи
053 ·····················<bs:guid></bs:guid> bs:UUID [0..1] Глобальный идентификатор объекта
054 ·····················<dt:name></dt:name> bs:String255 [1..1] Наименование адресного объекта
055 ··················</dt:cityArea>
056 ··················<dt:street> dt:Street [0..1] Улица
057 ·····················<bs:uuid></bs:uuid> bs:UUID [0..1] Идентификатор версии записи
058 ·····················<bs:guid></bs:guid> bs:UUID [0..1] Глобальный идентификатор объекта
059 ·····················<dt:name></dt:name> bs:String255 [1..1] Наименование адресного объекта
060 ··················</dt:street>
061 ··················<dt:landPlot> dt:LandPlot [0..1] Земельный участок
062 ·····················<bs:uuid></bs:uuid> bs:UUID [0..1] Идентификатор версии записи
063 ·····················<bs:guid></bs:guid> bs:UUID [0..1] Глобальный идентификатор объекта
064 ·····················<dt:name></dt:name> bs:String255 [1..1] Наименование адресного объекта
065 ··················</dt:landPlot>
066 ··················<dt:building> dt:Building [0..1] Здание
067 ·····················<bs:uuid></bs:uuid> bs:UUID [0..1] Идентификатор версии записи
068 ·····················<bs:guid></bs:guid> bs:UUID [0..1] Глобальный идентификатор объекта
069 ·····················<dt:name></dt:name> bs:String255 [1..1] Наименование адресного объекта
070 ·····················<dt:block> dt:Apartment [0..1] Строение (сооружение)
071 ························<dt:name></dt:name> bs:String255 [1..1] Наименование строения
072 ·····················</dt:block>
073 ··················</dt:building>
074 ··················<dt:apartment> dt:Apartment [0..1] Помещение
075 ·····················<bs:uuid></bs:uuid> bs:UUID [0..1] Идентификатор версии записи
076 ·····················<bs:guid></bs:guid> bs:UUID [0..1] Глобальный идентификатор объекта
077 ·····················<dt:name></dt:name> bs:String255 [1..1] Наименование адресного объекта
078 ··················</dt:apartment>
079 ··················<dt:room> dt:Apartment [0..1] Помещение в пределах помещения
080 ·····················<bs:uuid></bs:uuid> bs:UUID [0..1] Идентификатор версии записи
081 ·····················<bs:guid></bs:guid> bs:UUID [0..1] Глобальный идентификатор объекта
082 ·····················<dt:name></dt:name> bs:String255 [1..1] Наименование адресного объекта
083 ··················</dt:room>
084 ··················<dt:carPlace> dt:Apartment [0..1] Машино-место
085 ·····················<bs:uuid></bs:uuid> bs:UUID [0..1] Идентификатор версии записи
086 ·····················<bs:guid></bs:guid> bs:UUID [0..1] Глобальный идентификатор объекта
087 ·····················<dt:name></dt:name> bs:String255 [1..1] Наименование адресного объекта
088 ··················</dt:carPlace>
089 ··················<dt:postIndex></dt:postIndex> bs:String255 [0..1] Почтовый индекс
090 ··················<dt:postBox></dt:postBox> bs:String255 [0..1] Абонентский ящик
091 ··················<dt:additionalInfo></dt:additionalInfo> bs:String255 [0..1] Дополнительная информация об адресе
092 ··················<dt:addressView></dt:addressView> bs:String255 [0..1] Строковое представление адреса
093 ···············</dt:juridicalAddress>
094 ···············<dt:registryStatus></dt:registryStatus> dt:BusinessEntityStatus [1..1]

Статус хозяйствующего субъекта в реестре

  • UNVERIFIED — не подтверждён (не в реестре);
  • VERIFIED — подтверждён (включён в реестр);
  • CANCELED — исключён из реестра;
  • DELETED — удалён;
  • ELIMINATED — прекратил деятельность (исключён из реестра).
095 ············</dt:businessEntity>
·········</dt:businessEntityList>
······</mplc:checkBusinessEntityResponse>
···</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:checkBusinessEntityRequest>
        <mplc:localTransactionId>MP-20261001-000123</mplc:localTransactionId>
        <mplc:initiator><vd:login>marketplace.user01</vd:login></mplc:initiator>
        <dt:businessEntity>
          <dt:inn>7701234567</dt:inn>
          <dt:kpp>770101001</dt:kpp>
        </dt:businessEntity>
      </mplc:checkBusinessEntityRequest>
    </apl:data>
  </apl:application>
</def:submitApplicationRequest>

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

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

<mplc:checkBusinessEntityResponse>
  <dt:businessEntityList total="1" offset="0" count="1">
    <dt:businessEntity>
      <bs:uuid>…</bs:uuid>
      <bs:guid>1f2e3d4c-5b6a-4f7e-8d9c-0a1b2c3d4e5f</bs:guid>
      <dt:type>1</dt:type>
      <dt:inn>7701234567</dt:inn>
      <dt:kpp>770101001</dt:kpp>
      <dt:registryStatus>VERIFIED</dt:registryStatus>
      <!-- juridicalAddress — только для юридических лиц (type=1) -->
    </dt:businessEntity>
  </dt:businessEntityList>
</mplc:checkBusinessEntityResponse>
<!-- Если продавец не найден или не подтверждён в реестре:
     <mplc:checkBusinessEntityResponse><dt:businessEntityList total="0" offset="0" count="0"/></mplc:checkBusinessEntityResponse> -->

Варианты сценариев поиска (хотя бы один критерий внутри dt:businessEntity): 

<!-- по guid -->
<dt:businessEntity><bs:guid>1f2e3d4c-5b6a-4f7e-8d9c-0a1b2c3d4e5f</bs:guid></dt:businessEntity>
<!-- по ОГРН/ОГРНИП -->
<dt:businessEntity><dt:ogrn>1157700123456</dt:ogrn></dt:businessEntity>

Коды ошибок

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

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

Ошибки валидации профиля — коды назначаются разработчиком при реализации, тексты (проектные):

Условие Причина Текст ошибки (проектный)
Нет ни одного поискового критерия — guid, inn, ogrn не переданы в запросе Запрос без критериев выродился бы в «выдать всех ХС», что профилем запрещено «В запросе не указан ни один поисковый критерий. Передать guid, inn или ogrn.»
Передан kpp без inn КПП — только уточняющий критерий к ИНН; по КПП без ИНН искать нельзя «КПП может передаваться только вместе с ИНН. Передать inn или исключить kpp из запроса.»

Что НЕ является ошибкой:

  • Продавец не найден или не подтверждён в реестре — заявка выполняется успешно (COMPLETED): в ответе возвращается пустой список (count = 0). Пустой список означает, что во ФГИС «ВетИС» нет продавца по указанным поисковым критериям.

Источник

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