# 1 Требования к порядку взаимодействия и форматам обмена



# 1.1 Общие требования

<span style="font-family: PT Astra Serif, serif;">СМО взаимодействует с ФЕРЗЛ посредством SOAP-сервисов, использующих XML.</span>

<span style="font-family: PT Astra Serif, serif;">Взаимодействие осуществляется с использованием синхронных и асинхронных SOAP-методов.</span>

<span style="font-family: PT Astra Serif, serif;">Процесс синхронного взаимодействия ФЕРЗЛ с внешними системами состоит из следующих этапов:</span>

- <span style="font-family: PT Astra Serif, serif;">внешняя система через <span lang="en-GB">SOAP</span>-сервисы ФЕРЗЛ посылает запрос;</span>
- <span style="font-family: PT Astra Serif, serif;">ФЕРЗЛ принимает запрос, обрабатывает его и формирует ответное сообщение, содержащее информацию об успешности или неуспешности проведения операции, а также результаты ФЛК.</span>

<span style="font-family: PT Astra Serif, serif;">Операции, выполняемые асинхронно, выделены в отдельный сервис, где каждая операция представлена двумя методами:</span>

- <span style="font-family: PT Astra Serif, serif;">Start – запускает операцию и сообщает ее токен - строку, уникально идентифицирующую операцию;</span>
- <span style="font-family: PT Astra Serif, serif;">Poll – опрашивает готовность операции, предъявляя токен.</span>

<span style="font-family: PT Astra Serif, serif;">Системные результаты выполнения метода возвращаются как код ответа.</span>

<span style="font-family: PT Astra Serif, serif;">В случае, если полученные входные данные не проходят ФЛК, возвращаются коды результата и сообщения об ошибках, препятствующих выполнению операции.</span>

<span style="font-family: PT Astra Serif, serif;">При получении ошибки, данные должны быть откорректированы, и метод должен быть вызван повторно.</span>

<span style="font-family: PT Astra Serif, serif;">Каждому новому отправляемому запросу должен присваиваться новый внешний идентификатор, уникальный в рамках конкретной внешней информационной системы. Для передачи больших объёмов данных используется технология MTOM.</span>

<span style="font-family: PT Astra Serif, serif;">Таблица — Коды и сообщения об ошибках</span>

<table cellpadding="7" cellspacing="0" id="bkmrk-%E2%84%96-%D0%9A%D0%BE%D0%B4-%D1%81%D1%82%D0%B0%D1%82%D1%83%D1%81%D0%B0-%D0%BE%D1%88%D0%B8%D0%B1%D0%BA%D0%B8" width="623"><colgroup><col width="22"></col> <col width="62"></col> <col width="190"></col> <col width="292"></col> </colgroup><thead><tr><td width="22">№

</td><td width="62">**Код статуса ошибки**

</td><td width="190">**Значение**

</td><td width="292">**Возможные причины возникновения ошибки**

</td></tr></thead><tbody><tr><td valign="top" width="22">1. 

</td><td width="62">400

</td><td width="190">Ошибка в формате запроса

</td><td width="292">Формируется вне прикладного кода.

</td></tr><tr><td valign="top" width="22">2. 

</td><td width="62">401

</td><td width="190">Ошибка аутентификации

</td><td width="292">Неправильный пароль, истёкший токен доступа и т.п.

</td></tr><tr><td valign="top" width="22">3. 

</td><td width="62">403

</td><td width="190">Ошибка доступа к ресурсу

</td><td width="292">Попытка вызвать запрос, на который у текущей сессии нет прав.

</td></tr><tr><td valign="top" width="22">4. 

</td><td width="62">409

</td><td width="190">Ошибка бизнес-логики

</td><td width="292">Введены противоречивые/некорректные параметры.

</td></tr><tr valign="top"><td width="22">5. 

</td><td width="62">422

</td><td width="190">Необрабатываемый контент

</td><td width="292"><span style="font-family: PT Astra Serif, serif;"><span style="font-size: small;"><span style="font-family: Times New Roman, serif;"><span style="font-size: medium;">Ключи для организации не найдены,</span></span></span></span>

<span style="font-family: PT Astra Serif, serif;"><span style="font-size: small;"><span style="font-family: Times New Roman, serif;"><span style="font-size: medium;">Переданное значение не является ОИП, </span></span></span></span>

Версия справочника ключей не найдена

</td></tr><tr><td valign="top" width="22">6. 

</td><td width="62">500

</td><td width="190">Системная ошибка

</td><td width="292">Ошибка инфраструктуры.

</td></tr><tr><td valign="top" width="22">7. 

</td><td width="62">200

</td><td width="190">ОК

</td><td width="292"></td></tr></tbody></table>

# 1.2 Схема взаимодействия

#### <span style="font-family: PT Astra Serif, serif;">**1.2.1 Синхронные методы**</span>

[![image.png](https://bs.elforcer.ru/uploads/images/gallery/2024-10/scaled-1680-/lsHKeVpeNtdtMdct-Vcjimage.png)](https://bs.elforcer.ru/uploads/images/gallery/2024-10/lsHKeVpeNtdtMdct-Vcjimage.png)

#### <span style="font-family: PT Astra Serif, serif;">**1.2.2 Асинхронные методы**</span>

[![image.png](https://bs.elforcer.ru/uploads/images/gallery/2024-10/scaled-1680-/Eba2QRPa0kwa70rF-Xtdimage.png)](https://bs.elforcer.ru/uploads/images/gallery/2024-10/Eba2QRPa0kwa70rF-Xtdimage.png)

# 1.3 Аутентификация и авторизация

#### <span style="font-family: PT Astra Serif, serif;">**1.3.1 Подключение с использованием токена**</span>

<span style="font-family: PT Astra Serif, serif;">Пример токена:</span>

<table cellpadding="7" cellspacing="0" id="bkmrk-eyj0exaioijkv1qilcjh" width="623"><colgroup><col width="607"></col> </colgroup><tbody><tr><td valign="top" width="607"><a name="_Hlk155796357"></a> <span style="font-family: PT Astra Serif, serif;"><span style="font-size: small;">eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhZG1pbiIsInNlc3Npb24taWQiOiI5NGRkMDUwNy1hYWM0LTRlMmYtYmQ3OS1lNWQzMjQ2MjU2NGQifQ.QuzmHFYA4uRkLI1MKKT99EZN8A62-39-XnBJVrHoZ3U</span></span>

</td></tr></tbody></table>

<span style="font-family: PT Astra Serif, serif;">Для передачи токена в запрос необходимо в http запрос передать заголовок "X-Auth-Token" с содержанием токена.</span>

<span style="font-family: PT Astra Serif, serif;">Пример запроса:</span>

<table cellpadding="7" cellspacing="0" id="bkmrk-curl--h-%22x-auth-toke" width="623"><colgroup><col width="607"></col> </colgroup><tbody><tr><td valign="top" width="607"><span style="font-family: PT Astra Serif, serif;"><span style="font-size: small;">curl -H "X-Auth-Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJhZG1pbiIsInNlc3Npb24taWQiOiI5NGRkMDUwNy1hYWM0LTRlMmYtYmQ3OS1lNWQzMjQ2MjU2NGQifQ.QuzmHFYA4uRkLI1MKKT99EZN8A62-39-XnBJVrHoZ3U" http://hostname/api/some</span></span>

</td></tr></tbody></table>

# 1.4 Версионирование в ФЕРЗЛ

#### <span style="font-family: PT Astra Serif, serif;">**1.4.1 Цели**</span>

<span style="font-family: PT Astra Serif, serif;">Версионирование API предназначено для обеспечения своевременного обновления решения у потребителей:</span>

- <span style="font-family: PT Astra Serif, serif;">Своевременное − поддерживается работа нескольких версий (поддерживается наличие не более трёх версий API) для обеспечения асинхронного обновления у потребителей, синхронное обновление желательно, но не обязательно.</span>
- <span style="font-family: PT Astra Serif, serif;">Решение − версионируется все решение целиком при изменении любого компонента в составе, версионирование отдельных сервисов и методов не ведется.</span>

#### <span style="font-family: PT Astra Serif, serif;">**1.4.2 Версии API**</span>

<span style="font-family: PT Astra Serif, serif;">Каждая версия отличается своим набором уникальных атрибутов:</span>

- <span style="font-family: PT Astra Serif, serif;">WSDL</span>
- <span style="font-family: PT Astra Serif, serif;">XSD</span>

<span style="font-family: PT Astra Serif, serif;">Общая формула формирования ссылок на версии:</span>

<span style="font-family: PT Astra Serif, serif;">%хост\_стенда%/api/<span lang="en-US">smo</span>/integration/ws/%номер\_версии%/%тип\_атрибута%/%название\_сервиса%</span>

<span style="font-family: PT Astra Serif, serif;">где внутри %% указаны значения, которые должны быть изменены для получения рабочих ссылок</span>

##### <span style="font-family: PT Astra Serif, serif;">Версия 24.2.3 СМО</span>

- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">WSDL</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.3/mpiPolicyApplication.wsdl</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.3/mpiNR.wsdl</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.3/mpiPersonInfo.wsdl</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.3/mpiAsyncOperations.wsdl</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.3/mpiLegalRepresentation.wsdl</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.3/mpiStatusService.wsdl</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">XSD</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.3/mpiPolicyApplicationSchema.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.3/commonTypesSchema.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.3/mpiNRSchema.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.3/mpiPersonInfoSchema.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.3/mpiAsyncOperationsSchema.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.3/mpiLegalRepresentationSchema.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.3/mpiStatusServiceSchema.xsd</span></span>

##### <span style="font-family: PT Astra Serif, serif;">Версия 24.2.5 СМО</span>

- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">WSDL</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.5/mpiPolicyApplication.wsdl</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.5/mpiNR.wsdl</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.5/mpiPersonInfo.wsdl</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.5/mpiAsyncOperations.wsdl</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.5/mpiLegalRepresentation.wsdl</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.5/mpiStatusService.wsdl</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.5/mpiPersonObjectsControl.wsdl</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">XSD</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.5/mpiPolicyApplicationSchema.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.5/commonTypesSchema.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.5/mpiNRSchema.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.5/mpiPersonInfoSchema.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.5/mpiAsyncOperationsSchema.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.5/mpiLegalRepresentationSchema.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.5/mpiStatusServiceSchema.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.5/mpiPersonObjectsControlSchema.xsd</span></span>

##### <span style="font-family: PT Astra Serif, serif;">Версия 24.2.<span lang="en-US">6</span> СМО</span>

- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">WSDL</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.6/mpiPolicyApplication.wsdl</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.6/mpiNR.wsdl</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.6/mpiPersonInfo.wsdl</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.6/mpiAsyncOperations.wsdl</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.6/mpiLegalRepresentation.wsdl</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.6/mpiStatusService.wsdl</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.6/mpiPersonObjectsControl.wsdl</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">XSD</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.6/mpiPolicyApplicationSchema.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.6/commonTypesSchema.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.6/mpiNRSchema.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.6/mpiPersonInfoSchema.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.6/mpiAsyncOperationsSchema.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.6/mpiLegalRepresentationSchema.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.6/mpiStatusServiceSchema.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">/api/smo/integration/24.2.6/mpiPersonObjectsControlSchema.xsd</span></span>

#### <span style="font-family: PT Astra Serif, serif;">**1.4.3 Версии элементов data (структура подписываемых документов)**</span>

<span style="font-family: PT Astra Serif, serif;">В версиях API, начиная с 24.1.4, структура &lt;element name="data" type="base64Binary"/&gt; версионируется по конкретным типам документов (в рамках вложения doc\_service\_xsd), отдельно от версионирования API.</span>

<span style="font-family: PT Astra Serif, serif;">Поддерживается наличие не более трёх версий одной схемы элементов data.</span>

##### <span style="font-family: PT Astra Serif, serif;">Версия<span lang="en-US"> doc\_service\_for\_smo\_adapter\_24.1.1</span></span>

- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">WSDL</span></span><span style="font-family: PT Astra Serif, serif;"> (</span><span style="font-family: PT Astra Serif, serif;">не</span><span style="font-family: PT Astra Serif, serif;"> </span><span style="font-family: PT Astra Serif, serif;">предполагается</span><span style="font-family: PT Astra Serif, serif;">)</span>
- <span style="font-family: PT Astra Serif, serif;"> </span><span style="font-family: PT Astra Serif, serif;"><span lang="en-US">XSD</span></span><span style="font-family: PT Astra Serif, serif;"> (с</span><span style="font-family: PT Astra Serif, serif;">хемы xsd, применяемые для валидации элементов data, содержащих массив байт с подписанным документом</span><span style="font-family: PT Astra Serif, serif;">)</span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">commonTypes.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">mpiPolicyApplicationSchema.xsd</span></span>

##### <span style="font-family: PT Astra Serif, serif;">Версия<span lang="en-US"> doc\_service\_for\_smo\_adapter\_24.1.2</span></span>

- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">WSDL</span></span><span style="font-family: PT Astra Serif, serif;"> (</span><span style="font-family: PT Astra Serif, serif;">не</span><span style="font-family: PT Astra Serif, serif;"> </span><span style="font-family: PT Astra Serif, serif;">предполагается</span><span style="font-family: PT Astra Serif, serif;">)</span>
- <span style="font-family: PT Astra Serif, serif;"> </span><span style="font-family: PT Astra Serif, serif;"><span lang="en-US">XSD</span></span><span style="font-family: PT Astra Serif, serif;"> (с</span><span style="font-family: PT Astra Serif, serif;">хемы xsd, применяемые для валидации элементов data, содержащих массив байт с подписанным документом</span><span style="font-family: PT Astra Serif, serif;">)</span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">commonTypes.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">mpiPolicyApplicationSchema.xsd</span></span>

##### <span style="font-family: PT Astra Serif, serif;">Версия<span lang="en-US"> doc\_service\_for\_smo\_adapter\_24.1.4</span></span>

- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">WSDL</span></span><span style="font-family: PT Astra Serif, serif;"> (</span><span style="font-family: PT Astra Serif, serif;">не</span><span style="font-family: PT Astra Serif, serif;"> </span><span style="font-family: PT Astra Serif, serif;">предполагается</span><span style="font-family: PT Astra Serif, serif;">)</span>
- <span style="font-family: PT Astra Serif, serif;"> </span><span style="font-family: PT Astra Serif, serif;"><span lang="en-US">XSD</span></span><span style="font-family: PT Astra Serif, serif;"> (с</span><span style="font-family: PT Astra Serif, serif;">хемы xsd, применяемые для валидации элементов data, содержащих массив байт с подписанным документом</span><span style="font-family: PT Astra Serif, serif;">)</span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">commonTypes.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">mpiPolicyApplicationSchema.xsd</span></span>

##### <span style="font-family: PT Astra Serif, serif;">Версия<span lang="en-US"> doc\_service\_for\_smo\_adapter\_24.1.5</span></span>

- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">WSDL</span></span><span style="font-family: PT Astra Serif, serif;"> (</span><span style="font-family: PT Astra Serif, serif;">не</span><span style="font-family: PT Astra Serif, serif;"> </span><span style="font-family: PT Astra Serif, serif;">предполагается</span><span style="font-family: PT Astra Serif, serif;">)</span>
- <span style="font-family: PT Astra Serif, serif;"> </span><span style="font-family: PT Astra Serif, serif;"><span lang="en-US">XSD</span></span><span style="font-family: PT Astra Serif, serif;"> (с</span><span style="font-family: PT Astra Serif, serif;">хемы xsd, применяемые для валидации элементов data, содержащих массив байт с подписанным документом</span><span style="font-family: PT Astra Serif, serif;">)</span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">commonTypes.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">mpiLegalRepresentationSchema.xsd</span></span>

##### <span style="font-family: PT Astra Serif, serif;">Версия<span lang="en-US"> doc\_service\_for\_smo\_adapter\_24.1.6</span></span>

- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">WSDL</span></span><span style="font-family: PT Astra Serif, serif;"> (</span><span style="font-family: PT Astra Serif, serif;">не</span><span style="font-family: PT Astra Serif, serif;"> </span><span style="font-family: PT Astra Serif, serif;">предполагается</span><span style="font-family: PT Astra Serif, serif;">)</span>
- <span style="font-family: PT Astra Serif, serif;"> </span><span style="font-family: PT Astra Serif, serif;"><span lang="en-US">XSD</span></span><span style="font-family: PT Astra Serif, serif;"> (с</span><span style="font-family: PT Astra Serif, serif;">хемы xsd, применяемые для валидации элементов data, содержащих массив байт с подписанным документом</span><span style="font-family: PT Astra Serif, serif;">)</span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">commonTypes.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">mpiLegalRepresentationSchema.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">mpiStatusServiceSchema.xsd</span></span>

##### <span style="font-family: PT Astra Serif, serif;">Версия<span lang="en-US"> doc\_service\_for\_smo\_adapter\_24.2.5</span></span>

- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">WSDL</span></span><span style="font-family: PT Astra Serif, serif;"> (</span><span style="font-family: PT Astra Serif, serif;">не</span><span style="font-family: PT Astra Serif, serif;"> </span><span style="font-family: PT Astra Serif, serif;">предполагается</span><span style="font-family: PT Astra Serif, serif;">)</span>
- <span style="font-family: PT Astra Serif, serif;"> </span><span style="font-family: PT Astra Serif, serif;"><span lang="en-US">XSD</span></span><span style="font-family: PT Astra Serif, serif;"> (с</span><span style="font-family: PT Astra Serif, serif;">хемы xsd, применяемые для валидации элементов data, содержащих массив байт с подписанным документом</span><span style="font-family: PT Astra Serif, serif;">)</span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">commonTypes.xsd</span></span>
- <span style="font-family: PT Astra Serif, serif;"><span lang="en-US">mpiPersonObjectsControlSchema.xsd</span></span>