1 Требования к порядку взаимодействия и форматам обмена
- 1.1 Общие требования
- 1.2 Схема взаимодействия
- 1.3 Аутентификация и авторизация
- 1.4 Версионирование в ФЕРЗЛ
1.1 Общие требования
СМО взаимодействует с ФЕРЗЛ посредством SOAP-сервисов, использующих XML.
Взаимодействие осуществляется с использованием синхронных и асинхронных SOAP-методов.
Процесс синхронного взаимодействия ФЕРЗЛ с внешними системами состоит из следующих этапов:
-
внешняя система через SOAP-сервисы ФЕРЗЛ посылает запрос;
-
ФЕРЗЛ принимает запрос, обрабатывает его и формирует ответное сообщение, содержащее информацию об успешности или неуспешности проведения операции, а также результаты ФЛК.
Операции, выполняемые асинхронно, выделены в отдельный сервис, где каждая операция представлена двумя методами:
-
Start – запускает операцию и сообщает ее токен - строку, уникально идентифицирующую операцию;
-
Poll – опрашивает готовность операции, предъявляя токен.
Системные результаты выполнения метода возвращаются как код ответа.
В случае, если полученные входные данные не проходят ФЛК, возвращаются коды результата и сообщения об ошибках, препятствующих выполнению операции.
При получении ошибки, данные должны быть откорректированы, и метод должен быть вызван повторно.
Каждому новому отправляемому запросу должен присваиваться новый внешний идентификатор, уникальный в рамках конкретной внешней информационной системы. Для передачи больших объёмов данных используется технология MTOM.
Таблица — Коды и сообщения об ошибках
|
№ |
Код статуса ошибки |
Значение |
Возможные причины возникновения ошибки |
|
|
400 |
Ошибка в формате запроса |
Формируется вне прикладного кода. |
|
|
401 |
Ошибка аутентификации |
Неправильный пароль, истёкший токен доступа и т.п. |
|
|
403 |
Ошибка доступа к ресурсу |
Попытка вызвать запрос, на который у текущей сессии нет прав. |
|
|
409 |
Ошибка бизнес-логики |
Введены противоречивые/некорректные параметры. |
|
|
422 |
Необрабатываемый контент |
Ключи для организации не найдены, Переданное значение не является ОИП, Версия справочника ключей не найдена |
|
|
500 |
Системная ошибка |
Ошибка инфраструктуры. |
|
|
200 |
ОК |
|
1.2 Схема взаимодействия
1.2.1 Синхронные методы
1.2.2 Асинхронные методы
1.3 Аутентификация и авторизация
1.3.1 Подключение с использованием токена
Пример токена:
|
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhZG1pbiIsInNlc3Npb24taWQiOiI5NGRkMDUwNy1hYWM0LTRlMmYtYmQ3OS1lNWQzMjQ2MjU2NGQifQ.QuzmHFYA4uRkLI1MKKT99EZN8A62-39-XnBJVrHoZ3U |
Для передачи токена в запрос необходимо в http запрос передать заголовок "X-Auth-Token" с содержанием токена.
Пример запроса:
|
curl -H "X-Auth-Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhZG1pbiIsInNlc3Npb24taWQiOiI5NGRkMDUwNy1hYWM0LTRlMmYtYmQ3OS1lNWQzMjQ2MjU2NGQifQ.QuzmHFYA4uRkLI1MKKT99EZN8A62-39-XnBJVrHoZ3U" http://hostname/api/some |
1.4 Версионирование в ФЕРЗЛ
1.4.1 Цели
Версионирование API предназначено для обеспечения своевременного обновления решения у потребителей:
-
Своевременное − поддерживается работа нескольких версий (поддерживается наличие не более трёх версий API) для обеспечения асинхронного обновления у потребителей, синхронное обновление желательно, но не обязательно.
-
Решение − версионируется все решение целиком при изменении любого компонента в составе, версионирование отдельных сервисов и методов не ведется.
1.4.2 Версии API
Каждая версия отличается своим набором уникальных атрибутов:
-
WSDL
-
XSD
Общая формула формирования ссылок на версии:
%хост_стенда%/api/smo/integration/ws/%номер_версии%/%тип_атрибута%/%название_сервиса%
где внутри %% указаны значения, которые должны быть изменены для получения рабочих ссылок
Версия 24.2.3 СМО
-
WSDL
-
/api/smo/integration/24.2.3/mpiPolicyApplication.wsdl
-
/api/smo/integration/24.2.3/mpiNR.wsdl
-
/api/smo/integration/24.2.3/mpiPersonInfo.wsdl
-
/api/smo/integration/24.2.3/mpiAsyncOperations.wsdl
-
/api/smo/integration/24.2.3/mpiLegalRepresentation.wsdl
-
/api/smo/integration/24.2.3/mpiStatusService.wsdl
-
XSD
-
/api/smo/integration/24.2.3/mpiPolicyApplicationSchema.xsd
-
/api/smo/integration/24.2.3/commonTypesSchema.xsd
-
/api/smo/integration/24.2.3/mpiNRSchema.xsd
-
/api/smo/integration/24.2.3/mpiPersonInfoSchema.xsd
-
/api/smo/integration/24.2.3/mpiAsyncOperationsSchema.xsd
-
/api/smo/integration/24.2.3/mpiLegalRepresentationSchema.xsd
-
/api/smo/integration/24.2.3/mpiStatusServiceSchema.xsd
Версия 24.2.5 СМО
-
WSDL
-
/api/smo/integration/24.2.5/mpiPolicyApplication.wsdl
-
/api/smo/integration/24.2.5/mpiNR.wsdl
-
/api/smo/integration/24.2.5/mpiPersonInfo.wsdl
-
/api/smo/integration/24.2.5/mpiAsyncOperations.wsdl
-
/api/smo/integration/24.2.5/mpiLegalRepresentation.wsdl
-
/api/smo/integration/24.2.5/mpiStatusService.wsdl
-
/api/smo/integration/24.2.5/mpiPersonObjectsControl.wsdl
-
XSD
-
/api/smo/integration/24.2.5/mpiPolicyApplicationSchema.xsd
-
/api/smo/integration/24.2.5/commonTypesSchema.xsd
-
/api/smo/integration/24.2.5/mpiNRSchema.xsd
-
/api/smo/integration/24.2.5/mpiPersonInfoSchema.xsd
-
/api/smo/integration/24.2.5/mpiAsyncOperationsSchema.xsd
-
/api/smo/integration/24.2.5/mpiLegalRepresentationSchema.xsd
-
/api/smo/integration/24.2.5/mpiStatusServiceSchema.xsd
-
/api/smo/integration/24.2.5/mpiPersonObjectsControlSchema.xsd
Версия 24.2.6 СМО
-
WSDL
-
/api/smo/integration/24.2.6/mpiPolicyApplication.wsdl
-
/api/smo/integration/24.2.6/mpiNR.wsdl
-
/api/smo/integration/24.2.6/mpiPersonInfo.wsdl
-
/api/smo/integration/24.2.6/mpiAsyncOperations.wsdl
-
/api/smo/integration/24.2.6/mpiLegalRepresentation.wsdl
-
/api/smo/integration/24.2.6/mpiStatusService.wsdl
-
/api/smo/integration/24.2.6/mpiPersonObjectsControl.wsdl
-
XSD
-
/api/smo/integration/24.2.6/mpiPolicyApplicationSchema.xsd
-
/api/smo/integration/24.2.6/commonTypesSchema.xsd
-
/api/smo/integration/24.2.6/mpiNRSchema.xsd
-
/api/smo/integration/24.2.6/mpiPersonInfoSchema.xsd
-
/api/smo/integration/24.2.6/mpiAsyncOperationsSchema.xsd
-
/api/smo/integration/24.2.6/mpiLegalRepresentationSchema.xsd
-
/api/smo/integration/24.2.6/mpiStatusServiceSchema.xsd
-
/api/smo/integration/24.2.6/mpiPersonObjectsControlSchema.xsd
1.4.3 Версии элементов data (структура подписываемых документов)
В версиях API, начиная с 24.1.4, структура <element name="data" type="base64Binary"/> версионируется по конкретным типам документов (в рамках вложения doc_service_xsd), отдельно от версионирования API.
Поддерживается наличие не более трёх версий одной схемы элементов data.
Версия doc_service_for_smo_adapter_24.1.1
-
WSDL (не предполагается)
-
XSD (схемы xsd, применяемые для валидации элементов data, содержащих массив байт с подписанным документом)
-
commonTypes.xsd
-
mpiPolicyApplicationSchema.xsd
Версия doc_service_for_smo_adapter_24.1.2
-
WSDL (не предполагается)
-
XSD (схемы xsd, применяемые для валидации элементов data, содержащих массив байт с подписанным документом)
-
commonTypes.xsd
-
mpiPolicyApplicationSchema.xsd
Версия doc_service_for_smo_adapter_24.1.4
-
WSDL (не предполагается)
-
XSD (схемы xsd, применяемые для валидации элементов data, содержащих массив байт с подписанным документом)
-
commonTypes.xsd
-
mpiPolicyApplicationSchema.xsd
Версия doc_service_for_smo_adapter_24.1.5
-
WSDL (не предполагается)
-
XSD (схемы xsd, применяемые для валидации элементов data, содержащих массив байт с подписанным документом)
-
commonTypes.xsd
-
mpiLegalRepresentationSchema.xsd
Версия doc_service_for_smo_adapter_24.1.6
-
WSDL (не предполагается)
-
XSD (схемы xsd, применяемые для валидации элементов data, содержащих массив байт с подписанным документом)
-
commonTypes.xsd
-
mpiLegalRepresentationSchema.xsd
-
mpiStatusServiceSchema.xsd
Версия doc_service_for_smo_adapter_24.2.5
-
WSDL (не предполагается)
-
XSD (схемы xsd, применяемые для валидации элементов data, содержащих массив байт с подписанным документом)
-
commonTypes.xsd
-
mpiPersonObjectsControlSchema.xsd