Подсистема обработки заявок в Ветис.API

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

Это сервис для выполнения бизнес-операций в специализированных информационных системах Аргус, Меркурий, Веста и т.д. В подсистеме реализован сервис ApplicationManagementService суть работы которого заключается в приеме, авторизации и маршрутизации заявки к той или иной целевой специализированной информационной системе, получение и предоставление внешней системе результатов обработки заявки.

Принципы взаимодействия

Работа с сервисом ApplicationManagementService реализована по псевдо-асинхронному принципу и осуществляется в два шага (оба из которых выполняются синхронно):

• 1 шаг – подача запроса с заявкой на выполнение бизнес-операции и получение результата приема заявки (идентификатора заявки);
• 2 шаг – подача запроса на получение результата обработки заявки/выполнения бизнес-операции.

Для данной схемы действуют следующие правила:

• Взаимодействие реализуется посредством запросов внешних информационных систем к ApplicationManagementService. "Ветис.API" не может выступать в роли инициатора запроса. Передача информации из "Ветис.API" осуществляется в виде ответа на запрос от внешней информационной системы.
• Любая операция в рамках информационного взаимодействия с "Ветис.API" представляет собой заявку на выполнение бизнес-операции. Заявка от внешней информационной системы попадает в ApplicationManagementService, где обрабатывается. Заявка проходит форматно-логический контроль, регистрацию (ей присваивается уникальный идентификатор), маршрутизируется на целевой внутренний сервис. ApplicationManagementService позволяет отслеживать состояние данной заявки и получать результат ее выполнения.

Предоставляемые сервисы

ApplicationManagementService является единой внешней точкой доступа ко всем внутренним бизнес-сервисам специализированных информационных систем. При обращении к ApplicationManagementService для маршрутизации заявки клиент в запросе должен указать идентификатор целевого внутреннего сервиса serviceId.

ApplicationManagementService предоставляет возможность обращения к следующим целевым сервисам (serviceId) специализированных информационных систем:

• mercury-g2b.service – сервис системы Меркурий, который обрабатывает заявки от информационных систем хозяйствующих субъектов;
• mercury-vu.service – сервис системы Меркурий, который обрабатывает заявки от информационных систем ветеринарных управлений.

Безопасность

Доступ к сервису ApplicationManagementService ограничивается с помощью ключей доступа к API (APIKey). Ключи доступа предоставляются при регистрации внешней информационной системы в качестве клиента "Ветис.API". APIKey - ключ, который идентифицирует клиентскую информационную систему. В сочетании с идентификатором пользователя (issuerId), этот ключ позволяет получать доступ к информации о клиенте сервиса (хозяйствующем субъекте или ветеринарном управлении).

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

Процесс авторизации при подключении к универсальному шлюзу "Ветис.API" описан здесь.

Бизнес-операции

Через "Ветис.API" реализована возможность подачи заявок на выполнение следующих операций:

Меркурий

Целевые сервисы mercury-g2b.service (для хозяйствующих субъектов) и mercury-vu.service (для ветеринарных управлений), набор операций в каждом сервисе совпадает.

Операции версии 1.*

• оформление производственной партии
• оформление транспортной партии
• оформление входящей партии
• оформление результатов инвентаризации
• объединение записей складского журнала
• получение ВСД по его идентификатору
• получение ВСД, созданных или измененных за указанный интервал дат (получение истории изменений)
• получение всех ВСД предприятия с возможностью фильтрации
• получение конкретной версии записи складского журнала по ее идентификатору
• получение последней (актуальной) версии записи складского журнала по ее идентификатору
• получение всех версий записи складского журнала по ее идентификатору
• получение актуального списка записей журнала
• получение списка версий записей журнала, созданных или измененных за указанный интервал дат (получение истории изменений)
• добавление/изменение сведений о хозяйствующем субъекте
• добавление/изменение сведений о поднадзорном объекте
• аннулирование ВСД
• создание/удаление связи с площадкой
• добавление номенклатуры производителя в справочник

Операции версии 2.*

• оформление производственной партии
• оформление транспортной партии
• оформление входящей партии
• оформление результатов инвентаризации
• объединение записей складского журнала
• получение ВСД по его идентификатору
• получение ВСД, созданных или измененных за указанный интервал дат (получение истории изменений)
• получение всех ВСД предприятия с возможностью фильтрации
• получение конкретной версии записи складского журнала по ее идентификатору
• получение последней (актуальной) версии записи складского журнала по ее идентификатору
• получение всех версий записи складского журнала по ее идентификатору
• получение актуального списка записей журнала
• получение списка версий записей журнала, созданных или измененных за указанный интервал дат (получение истории изменений)
• добавление/изменение сведений о хозяйствующем субъекте
• добавление/изменение сведений о поднадзорном объекте
• аннулирование ВСД
• создание/удаление связи с площадкой
• добавление номенклатуры производителя в справочник
• внесение номеров транспортных средств в пунктах перегрузки в оформленный ВСД
• внесение сведений о ветеринарных мероприятиях
• проверка возможности осуществления перевозки партии в рамках регионализации

Возможные сценарии

При обработке запроса возможны следующие сценарии.

1. Запрос успешно обработан.

• Заявка требует обработки.
  
• Результат сформирован в рамках запроса(cтатус заявки-completed).
  

2. Произошла ошибка при обработке запроса.

• Некорректный запрос.
  
• Запрос не прошёл проверку на бизнес-правила.
  
• Внутренняя ошибка системы.
  

На вход сервиса ApplicationManagementService передаются следующие сведения:

• API key;
• код запрашиваемого сервиса;
• идентификатор пользователя;
• заявка на выполнение операции.

Результатом обработки заявки в заявочной системе является:

• сгенерированный идентификатор заявки;
• статус готовности результата.

Для получения результата обработки заявки необходимо запросить результат по идентификатору заявки.

Используемые пространства имен и типы

app (http://api.vetrf.ru/schema/cdm/application) app:APIKey app:Application app:ApplicationDataWrapper app:ApplicationStatus app:ApplicationResultWrapper

bs (http://api.vetrf.ru/schema/cdm/base) bs:UUID xs (http://www.w3.org/2001/XMLSchema) xs:dateTime xs:NCName xs:string

Подача заявки

Данные запроса

Структура данных запроса в формате ХML.

  <ws:submitApplicationRequest>
    <ws:apiKey>{app:APIKey}</ws:apiKey>
    <app:application>
      <app:serviceId>{xs:NCName}</app:serviceId>
      <app:issuerId>{bs:UUID}</app:issuerId>
      <app:issueDate>{xs:dateTime}</app:issueDate>
      <app:data>{app:ApplicationDataWrapper}</app:data>
    </app:application>
  </ws:submitApplicationRequest>

Объект submitApplicationRequest

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

Поле	Описание	Тип	Обязательность
apiKey	Специальный код, который идентифицирует учетную запись пользователя и позволяет веб-сервису получить доступ к информации о хозяйствующем субъекте и обслуживаемых предприятиях, к которым данный пользователь относится.	app:APIKey	1
application	Сведения о заявке.	app:application	1

Объект submitApplicationRequest/application

Сведения о заявке.

Поле	Описание	Тип	Обязательность
serviceId	Код запрашиваемого сервиса (системы, к которой обращается пользователь). mercury-g2b.service - сервис системы Меркурий, который обрабатывает заявки от хозяйствующих субъектов. mercury-vu.service - сервис системы Меркурий, который обрабатывает заявки от ветеринарных управлений.	xs:NCName	1
issuerId	Идентификатор хозяйствующего субъекта от имени которого происходит обращение к Ветис.API. Указанный хозяйствующий субъект должен быть одним из хозяйствующих субъектов, обслуживаемых данной программной системой. Перечень обслуживаемых программной системой хозяйствующих субъектов устанавливается при предоставлении доступа к Ветис.API.	bs:UUID	1
issueDate	Дата и время обращения пользователя к заявочной системе. Устанавливается разработчиком клиентской системы.	xs:dateTime	1
data	Сведения о заявке.	app:ApplicationDataWrapper	1

Данные ответа

Структура данных запроса в формате ХML.

      <submitApplicationResponse xmlns="http://api.vetrf.ru/schema/cdm/application/ws-definitions">
         <application xmlns="http://api.vetrf.ru/schema/cdm/application">
            <applicationId>{bs:UUID}</applicationId>
            <status>{app:ApplicationStatus}</status>
            <serviceId>{xs:NCName}</serviceId>
            <issuerId>{bs:UUID}</issuerId>
            <issueDate>{xs:dateTime}</issueDate>
            <rcvDate>{xs:dateTime}</rcvDate>
         </application>
      </submitApplicationResponse>

Объект submitApplicationResponse

Заявка в заявочной системе, содержит сведения запроса.

Поле	Описание	Тип	Обязательность
application	Сведения о заявке.	app:Application	1

Объект submitApplicationResponse/application

Поле	Описание	Тип	Обязательность
applicationId	Сгенерированный идентификатор заявки.	bs:UUID	1
status	Статус готовности результата.	app:ApplicationStatus	1
serviceId	Код запрашиваемого сервиса (системы, к которой обращается пользователь).	xs:NCName	1
issuerId	Идентификатор хозяйствующего субъекта от имени которого происходит обращение к Ветис.API. Указанный хозяйствующий субъект должен быть одним из хозяйствующих субъектов, обслуживаемых данной программной системой. Перечень обслуживаемых программной системой хозяйствующих субъектов устанавливается при предоставлении доступа к Ветис.API.	bs:UUID	1
issueDate	Дата и время обращения пользователя к заявочной системе. Устанавливается разработчиком клиентской системы.	xs:dateTime	1
rcvDate	Дата и время формирования результата.	xs:dateTime	1

Получение результата обработки заявки

Данные запроса

Структура данных запроса в формате ХML.

<ws:receiveApplicationResultRequest>
    <ws:apiKey>{xs:string}</ws:apiKey>
    <ws:issuerId>{bs:UUID}</ws:issuerId>
    <ws:applicationId>{bs:UUID}</ws:applicationId>
</ws:receiveApplicationResultRequest>

Объект receiveApplicationResultRequest

Запрос на получение результатов обработки заявки.

Поле	Описание	Тип	Обязательность
apiKey	Специальный код, который идентифицирует учетную запись пользователя и позволяет веб-сервису получить доступ к информации о хозяйствующем субъекте и обслуживаемых предприятиях, к которым данный пользователь относится.	xs:string	1
issuerId	Идентификатор пользователя, обратившегося к заявочной системе.	bs:UUID	1
applicationId	Идентификатор заявки, в заявочной системе.	bs:UUID	1

Данные ответа

Структура данных ответа в формате ХML.

<receiveApplicationResultResponse xmlns="http://api.vetrf.ru/schema/cdm/application/ws-definitions">
    <application xmlns="http://api.vetrf.ru/schema/cdm/application">
        <applicationId>{bs:UUID}</applicationId>
        <status>{app:ApplicationStatus}</status>
        <serviceId>{xs:NCName}</serviceId>
        <issuerId>{bs:UUID}</issuerId>
        <issueDate>{xs:dateTime}</issueDate>
        <rcvDate>{xs:dateTime}</rcvDate>
        <prdcRsltDate>{xs:dateTime}</prdcRsltDate>
        <result>
            <...>
        </result>
    </application>
</receiveApplicationResultResponse>

Объект receiveApplicationResultResponse

Получение результатов обработки заявки.

Поле	Описание	Тип	Обязательность
application	Сведения о заявке.	app:Application	1

Объект receiveApplicationResultResponse/application

Поле	Описание	Тип	Обязательность
applicationId	Сгенерированный идентификатор заявки.	bs:UUID	1
status	Статус готовности результата.	app:ApplicationStatus	1
serviceId	Код запрашиваемого сервиса (системы, к которой обращается пользователь).	xs:NCName	1
issuerId	Идентификатор хозяйствующего субъекта от имени которого происходит обращение к Ветис.API. Указанный хозяйствующий субъект должен быть одним из хозяйствующих субъектов, обслуживаемых данной программной системой. Перечень обслуживаемых программной системой хозяйствующих субъектов устанавливается при предоставлении доступа к Ветис.API.	bs:UUID	1
issueDate	Дата и время обращения пользователя к заявочной системе. Устанавливается разработчиком клиентской системы.	xs:dateTime	1
rcvDate	Дата и время формирования результата.	xs:dateTime	1
prdcRsltDate	Дата и время получения результата выполнения заявки.	xs:dateTime	1
result	Результат выполнения заявки.	app:ApplicationResultWrapper	1