Оглавление

Общий порядок взаимодействия систем

Получение списка обязательных полей

Для получения списка первичных обязательных полей без привязки к конкретным инстанциям используются следующие API-методы:

Получение обязательных полей по типу клиента

POST /api/v1/service/profilebasefield/list

Используется для получения первичных обязательных полей зависимых от типа клиента (ФЛ или ИП/ЮЛ).

Раскрыть

title	Нажмите, чтобы посмотреть/скрыть пример

Пример тела запроса:

Блок кода
{ "clientType": "COMPANY" }

где clientType может иметь следующие значения:

"INDIVIDUAL" - физическое лицо;
"COMPANY" - юр.лицо/ИП.

Пример получаемого ответа:

Блок кода

{
    "result": [
        "regDate",
        "baseOkved",
        "okopf",
        "taxSystem",
        "legalType",
        "legalAddress",
        "legalAddress.city",
        "legalAddress.house",
        "legalAddress.isOwned",
        "legalAddress.postCode",
        "legalAddress.region",
        "legalAddress.street",
        "factAddress",
        "factAddress.city",
        "factAddress.house",
        "factAddress.isOwned",
        "factAddress.postCode",
        "factAddress.region",
        "factAddress.street",
        "sourceInfo",
        "sourceInfo.headCompany",
        "sourceInfo.hasBranches"
    ],
    "fetchFields": {}
}

Получение обязательных полей по типу продукта

POST /api/v1/service/productbasefield/list

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

Раскрыть

title	Нажмите, чтобы посмотреть/скрыть пример

Пример тела запроса:

Блок кода
{ "productType": "BG" }

Возможные значения productType см. в справочнике product_types.

Пример получаемого ответа:

Блок кода

{
    "result": [
        "BG:productDealState.amount",
        "BG:productDealState.tender.federalLaw",
        "BG:productDealState.customer.region",
        "BG:productDealState.startDate",
        "BG:productDealState.endDate",
        "BG:productDealState.deliveryIsRequired",
        "BG:productDealState.termDays"
    ],
    "fetchFields": {}
}

Поиск продуктов на основе имеющихся на текущий момент данных

POST /api/v1/deal/findProducts

Подсказка
Пример сообщения: findProducts.json

Информация о подходящих продуктах и требования по дальнейшему заполнению

Ответ, получаемый при выполнении findProducts, содержит список доступных продуктов

Раскрыть

title	Нажмите, чтобы посмотреть/скрыть пример ответа

Блок кода

{
    "result": [
      {
        "product": "7ab44246-4607-41f4-8272-8b2ed290e210:beff7718-c72b-43be-b7c6-aa58b1df3cca",
        "serviceCompanyErrors": [],
        "serviceProductErrors": [
          {
            "validator": {
              "field": "BG:productDealState.tender.enforceAmount",
              "type": "PRODUCT_FIELD_REQUIRED"
            },
            "count": 1
          }
        ],
        "serviceMissingClientDocTypes": [
            {
              "docType": "EXTRACT_FROM_LEGAL_PERSON_REGISTRY",
              "paramGroups": []
            }
          ],
        "serviceMissingDealDocTypes": [],
        "serviceMissingIndicators": [],
        "documentTooltips": [
            {
              "tooltip": null,
              "docTypes": [
                "HEAD_PASSPORT_COPY",
                "EXTRACT_FROM_LEGAL_PERSON_REGISTRY",
                "CHARTER",
                "HEAD_APPOINTMENT_PROTOCOL",
                "FINANCE_REPORT_LAST_QUARTER",
                "ANALYTICAL_BALANCE_LAST_REPORTING_YEAR"
              ]
            }
          ],
        "financeIndicatorTooltips": [],
        "tariffCompanyErrors": [],
        "tariffProductErrors": []
      }
    ],
    "fetchFields": {
      "Product": {
        "7ab44246-4607-41f4-8272-8b2ed290e210:beff7718-c72b-43be-b7c6-aa58b1df3cca": {
          "id": "7ab44246-4607-41f4-8272-8b2ed290e210:beff7718-c72b-43be-b7c6-aa58b1df3cca",
          "name": "Банковская гарантия на исполнение для ЮЛ банка ДЖОЛВЖД (ред.10.12.20)",
          "shortName": "БГ на исполнение, ЮЛ (ред.10.12.20, ДЖОЛВЖД)",
          "productType": "BG",
          "description": null,
          "state": "1",
          "author": "ServiceContactParticipant:806b9fea-0d07-4f18-bd9d-0ca3c1e9a346",
          "createDateTime": "2020-12-10T05:59:47.746426",
          "modifier": "ServiceContactParticipant:806b9fea-0d07-4f18-bd9d-0ca3c1e9a346",
          "modifiedDateTime": "2020-12-28T06:27:48.044206"
        }
      }
    }
}

Описание полей ответа

КлючОписаниеПрим.productСодержит ссылку на fetchField ProductserviceCompanyErrors

Содержит информацию о необходимых для заполнения полях продукта.
Перечень возможных значений см. в справочнике company_fields

serviceProductErrorsСодержит информацию о необходимых для заполнения полях продукта.
Перечень возможных значений см. в справочнике product_types_fieldsserviceMissingClientDocTypesСодержит список недостающих документов клиента.
Перечень возможных значений см. в справочнике docs_typesserviceMissingDealDocTypesСодержит список недостающих обязательных документов о сделке.serviceMissingIndicatorsСодержит список достающих обязательных фин.показателей.
Перечень возможных значений см. в справочнике finance_fieldsdocumentTooltips

Содержит список документов необходимых при заполнении
"либо документы, либо фин.показатели"

financeIndicatorTooltipsСодержит список фин.показателей необходимых при заполнении
"либо документы, либо фин.показатели"tariffCompanyErrorstariffProductErrors

Отправка заявки в сервисы с указанием продуктов

POST /api/v1/deal/send_applications

При отправке заявок указывается список целевых продуктов, и идентификаторы будущих заявок для соответствующего продукта. В dealState передается та же структура, что и ранее передавалась в /api/v1/deal/findProducts

Раскрыть

title	Нажмите, чтобы посмотреть/скрыть пример

Блок кода

{
  "toProducts": [
    {
      "productId": "7ab44246-4607-41f4-8272-8b2ed290e444:179f3310-9827-44a2-913a-515cf2c43721",
      "applicationId": "de74bb16-7d03-420f-9c84-f034f249a1b0"
    }
  ],
  "cbUrl": "https://some_host.com/cb"
  "dealState": <...>
}

Информация

В ближайшем будущем планируется вместо productId принимать токен, который будет возвращаться из findProducts. Так же вероятна замена передачи данных в dealState на указание URI, по которому можно получить данные, с поддержкой указания требуемых секций данных. Эти преобразования дадут возможность применить стиль REST с применением HATEOAS.

Информация о результате принятия заявки в работу

Система банка, получив заявку, делает первичную ее валидацию, по результатам которой она отправляет сообщение о успешном или провалившемся результате принятия заявки в обработку.

В атрибуте targetObjectId приходит идентификатор заявки, по которой пришел результат.

Раскрыть

title	Нажмите, чтобы посмотреть/скрыть пример

Структура сообщения об успешном принятии заявки в работу

Блок кода
{ "originatorMsgType": "AddDealApplication", "originatorMsgId": "a45f8520-b132-4ab4-82ce-562affdbed43", "targetObjectId": "333a7c64-973d-40ce-8fb5-18f228d89b8f", "result": "SUCCESS", "error": null }

Структура сообщения об ошибке

Блок кода

{
  "originatorMsgType": "AddDealApplication",
  "originatorMsgId": "e8eb698b-0dea-4fd7-a705-b254eb53e06f",
  "targetObjectId": "333a7c64-973d-40ce-8fb5-18f228d89b8f",
  "result": "ERROR",
  "error": {
    "id": "adbab53c-11aa-43c8-b9e1-8960a03d8ee0",
    "errorCode": "MY_ERROR_STATUS_1",
    "message": "Some message",
    "params": {
      "MY_PARAM_3": "VALUE3"
    }
  }
}

Сообщения отправляемые при изменении статуса заявок

Сообщение будет приходить на ранее указанный адрес обратного вызова.

В сообщении присутствует идентификатор заявки, который был ранее указан при "applicationId".

Информация

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

Раскрыть

title	Нажмите, чтобы посмотреть/скрыть пример

Блок кода

{
  "applicationId": "de74bb16-7d03-420f-9c84-f034f249a1b0",
  "displayStatus": "Готова к подписанию",
  "applicationStatus": "SENT_TO_SERVICE",
  "message": null,
  "userActions": [
    {
      "actionType": "CLIENT_INTERNAL_SIGN",
      "label": "Подписать",
      "description": "Подписать заявку",
      "documentsToSignUrl": "/deal/documents_to_sign/de74bb16-7d03-420f-9c84-f034f249a1b0"
    },
    {
      "actionType": "AGENT_GET_INTERNAL_SIGN_URL",
      "label": "Получить ссылку",
      "description": "Получить ссылку для подписания клиентом",
      "documentsToSignUrl": "/deal/documents_to_sign/de74bb16-7d03-420f-9c84-f034f249a1b0"
    }
  ]
}

Перечень возможных значений dealApplicationStatus см. в справочнике dealApplicationStatuses.

Перечень возможных userActions см. в справочнике userActions.

Информация

На текущий момент в прототипе не реализован проброс API для подписания документов, чтобы заявка могла считаться подписанной. Необходимые данные для получения и подписания документов предполагается указывать в виде соответствующих URI внутри каждого элемента userActions. Так же возможна реализация ресурса, для получения текущего состояния заявки, чтобы внешняя система могла в любой момент получить актуальное состояние заявки, и возможные действия по ней.

Не все требования к полям сервисы декларируют в своих продуктах, некоторые проверки они выполняют у себя самостоятельно, поэтому возможны статусы отклонения заявки.

Раскрыть

title	Нажмите, чтобы посмотреть/скрыть пример

Пример отклонения заявки

Блок кода

{
  "applicationId": "33c9e43e-82fd-43ea-8fbf-4d54fa4fa97f",
  "displayStatus": "Ошибка отправки",
  "applicationStatus": "REJECTED_BY_SERVICE",
  "message": "У компании-агента не заполнен ОКПО в карточке компании.\r\nУ компании-агента не заполнен базовый ОКВЭД в карточке компании.\r\nУ компании-агента не заполнен юридический адрес в карточке компании.\r\nУ компании-агента не заполнен тип организации в карточке компании.\r\nУ компании-агента не заполнен фактический адрес в карточке компании.",
  "userActions": []
}

Возможные значения applicationStatus:

ЗначениеОписаниеSENT_TO_SERVICEОтправлена в сервисCLOSED_BY_SYSTEMЗакрыта системой. Терминальный статусREJECTED_BY_SERVICEОтклонена сервисом (банком). Терминальный статусPRODUCT_ISSUEDВыпущен продукт. Терминальный статус

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

При получении события о смене статуса заявки, если в данном сообщении так же присутствует UserAction с типом CLIENT_INTERNAL_SIGN, система-отправитель должна выполнить действие подписания заявки. Процесс подписания заявки организован через подписание ее документов, куда входят как документы, которые были ранее присланы при подаче заявки, так и сгенерированные на стороне банка документы (например, анкета клиента).

Получить список документов, требуемых на подпись можно вызвав URL, указанный в атрибуте userActions[].documentsToSignUrl. В результате данного вызова будет получен список документов, с их хешами разных алгоритмов, для возможности подписания, и URL для скачивания (если пользователю или системе отправителю, потребуется содержимое документов).

Список возможных алгоритмов

GOST-3411,
GOST-3411-2012-512,
GOST-3411-2012-256,
SHA-256.

Так же в теле ответа приходит URL, на который необходимо отправлять результаты подписи. Данный URL определен в атрибуте result.signUrl.

Раскрыть

title	Нажмите, чтобы посмотреть/скрыть пример списка документов на подписание

Блок кода

{
    "result": {
        "signUrl": "/deal/servicedocument/quick/sign",
        "documents": [
            {
                "id": "684369",
                "dealApplicationId": "333a7c64-973d-40ce-8fb5-18f228d89b8f",
                "documentTypeName": "Копии паспортов Бенефициарных владельцев",
                "description": null,
                "files": [
                    {
                        "id": "NzY5Mjk1OkF0dGFjaG1lbnRz",
                        "filename": "mtsbank_logored_ru_rgb.jpg",
                        "url": "http://192.168.1.138:8080/bidders/dg/remote_download/Attachments/769295/7b2def6f-ecb9-49ad-a32a-e5327e889f6d/",
                        "comment": null,
                        "hashes": [
                            {
                                "algorithm": "GOST-3411-2012-512",
                                "hash": "{
    "result": {
        "signUrl": "/deal/servicedocument/quick/sign",
        "documents": [
            {
                "id": "684369",
                "dealApplicationId": "333a7c64-973d-40ce-8fb5-18f228d89b8f",
                "documentTypeName": "Копии паспортов Бенефициарных владельцев",
                "description": null,
                "files": [
                    {
                        "id": "NzY5Mjk1OkF0dGFjaG1lbnRz",
                        "filename": "mtsbank_logored_ru_rgb.jpg",
                        "url": "http://192.168.1.138:8080/bidders/dg/remote_download/Attachments/769295/7b2def6f-ecb9-49ad-a32a-e5327e889f6d/",
                        "comment": null,
                        "hashes": [
                            {
                                "algorithm": "GOST-3411-2012-512",
                                "hash": "<OMMITED>"
                            },
                            {
                                "algorithm": "GOST-3411-2012-256",
                                "hash": "<OMMITED>"
                            }
                        ]
                    },
                    {
                        "id": "NzY5Mjk2OkF0dGFjaG1lbnRz",
                        "filename": "test.docx",
                        "url": "http://192.168.1.138:8080/bidders/dg/remote_download/Attachments/769296/7b2def6f-ecb9-49ad-a32a-e5327e889f6d/",
                        "comment": null,
                        "hashes": [
                            {
                                "algorithm": "GOST-3411-2012-512",
                                "hash": "<OMMITED>"
                            },
                            {
                                "algorithm": "GOST-3411-2012-256",
                                "hash": "<OMMITED>"
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "fetchFields": {}
}

Раскрыть

title	Нажмите, чтобы посмотреть/скрыть пример сообщения с результатом подписания

Блок кода{ "signatures": [ { "dealApplicationId": "333a7c64-973d-40ce-8fb5-18f228d89b8f", "documentSignatures": [ { "serviceDocumentFileId": "Mjk4NjgxOkdlbmVyYXRlZERvY3VtZW50cw", "signature": "<OMMITED>" }, { "serviceDocumentFileId": "Mjk4NjgyOkdlbmVyYXRlZERvY3VtZW50cw", "signature": "<OMMITED>" }, { "serviceDocumentFileId": "MTEzMDc0MTpBdHRhY2htZW50cw", "signature": "<OMMITED>" } ] } ] }

Отображение дочерних

Create Branch

Дерево страниц

Сравнение версий

Старая версия 57

Новая версия Текущий

Ключ

Общий порядок взаимодействия систем

Получение списка обязательных полей

Получение обязательных полей по типу клиента

Получение обязательных полей по типу продукта

Поиск продуктов на основе имеющихся на текущий момент данных

Информация о подходящих продуктах и требования по дальнейшему заполнению

Описание полей ответа

Отправка заявки в сервисы с указанием продуктов

Информация о результате принятия заявки в работу

Структура сообщения об успешном принятии заявки в работу

Структура сообщения об ошибке

Сообщения отправляемые при изменении статуса заявок

Возможные значения applicationStatus:

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

Список возможных алгоритмов

Дерево страниц

История страницы

Сравнение версий

Старая версия 57

Новая версия Текущий

Ключ

Общий порядок взаимодействия систем

Получение списка обязательных полей

Получение обязательных полей по типу клиента

Получение обязательных полей по типу продукта

Поиск продуктов на основе имеющихся на текущий момент данных

Информация о подходящих продуктах и требования по дальнейшему заполнению

Описание полей ответа

Отправка заявки в сервисы с указанием продуктов

Информация о результате принятия заявки в работу

Структура сообщения об успешном принятии заявки в работу

Структура сообщения об ошибке

Сообщения отправляемые при изменении статуса заявок

Возможные значения applicationStatus:

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

Список возможных алгоритмов