Создание залога и назначение его к заявке на займ
Инструкция предназначена для сторонних разработчиков, интегрирующихся с API BrainySoft.
Цель: пошагово показать, как программно создать залог, настроить справочник «Типы залогов», инициализировать свойства залога и назначить залог к заявке на займ.
Краткий обзор процесса
Для выполнения полного бизнес-процесса необходимо последовательно выполнить следующие шаги:
| Шаг | Method | URI | Description |
|---|---|---|---|
| 1 | POST | /bs-core/dicts/collateral-types | Создание элемента справочника «Типы залогов» |
| 2 | POST | /bs-core/main/collaterals/properties/init/collateral-type-id/{collateralTypeId} | Инициализация свойств залога на основе типа |
| 3 | GET/PUT | /bs-core/dicts/collateral-types/{id} | Получение и редактирование типа залога |
| 4 | GET | /bs-core/main/collaterals/init | Инициализация нового залога |
| 5 | POST | /bs-core/main/collaterals | Создание залога |
| 6 | GET/PUT | /bs-core/main/loan-apps/{id} | Назначение залога к заявке на займ |
Результат: В системе будут созданы:
- Элемент справочника «Типы залогов».
- Залог с заполненными свойствами.
- Залог назначен к заявке на займ.
Важно: В данном сценарии используются только системно обязательные поля, что минимизирует риски ошибок и упрощает первоначальную интеграцию.
Предварительные требования
Для осуществления бизнес-процесса вам потребуется:
- Доступ к API BrainySoft и валидные учетные данные.
- Идентификатор клиента-залогодателя (depositorId).
- Идентификатор заявки на займ (loanAppId).
Шаг 1: Создание нового элемента в справочнике "Типы залогов"
Метод: POST /bs-core/dicts/collateral-types
Описание: Создается элемент справочника «Типы залогов» для дальнейшего использования в системе и привязки его к Залогу.
Документация:
Параметры запроса
Сформируйте объект типа залога на основе данных из примера запроса.
Важно
Для создания типа залога требуется заполнить обязательные поля, указанные в таблице ниже.
| Группа полей | Параметр | Обязательность | Тип | Описание | Примечание |
|---|---|---|---|---|---|
| Основные | id | R | int | Идентификатор типа залога | При создании нового элемента — null |
| name | R | string | Наименование типа залога | "Авто тест2" | |
| bureauCode | R | int | Код для бюро | "5" | |
| active | R | bool | Действующий (Да/Нет) | true | |
| priorityNumber | R | int | Номер свойства залога | null | |
| Свойства | collateralPropertiesTypes._.collateralPropertyTypeId | М | int | Идентификатор свойства типа залога | null |
| collateralPropertiesTypes._.value | М | string | Значение свойства типа залога | null | |
| collateralPropertiesTypes._.valueCustomDictId | М | int | Значение идентификатора пользовательского справочника | Для выбора справочника при свойств залога (создание пользовательского справочника) | |
| collateralPropertiesTypes._.orderId | М | int | Порядковый номер | 0 |
Пример запроса
POST /bs-core/dicts/collateral-types{
"name": "Авто тест2",
"bureauCode": "5",
"collateralPropertyTypes": [
{
"collateralPropertyTypeId": null,
"value": null,
"valueCustomDictId": null,
"orderId": 0
}
],
"active": true,
"priorityNumber": null,
"id": null
}Пример успешного ответа
Метод вернет JSON-объект с идентификатором типа залога collateralTypeId, сохраните его для использования на следующем шаге и при создании Залога. ID типа залога возвращается в поле "data": 1017549.
{
"status": "ok",
"timestamp": 1764085203092,
"data": 1017549
}Сохраните id типа залога (значение поля "data") — он понадобится для следующих шагов.
Шаг 2: Инициализация свойств залога на основе типа залога
Метод: POST /bs-core/main/collaterals/properties/init/collateral-type-id/{collateralTypeId}
Описание: Метод предназначен для получения предварительно инициализированного объекта залога на основе его типа. Все обязательные поля и свойства, связанные с типом залога, заполняются значениями по умолчанию (например, null, 0, пустыми коллекциями). Для упрощения на клиентской стороне формирования корректного запроса для последующего создания или редактирования залога.
Документация: Инициализация свойств залога на основе типа залога
Параметры запроса
{collateralTypeId} (integer, обязательный) — уникальный идентификатор типа залога, созданного на Шаге 1.
Тело запроса
Сформируйте объект залога на основе данных из примера запроса.
| Группа полей | Параметр | Обязательность | Тип | Описание | Примечание |
|---|---|---|---|---|---|
| Основные | collateralTypeId | R | int | Идентификатор типа залога | Формируется на Шаге 1 |
| depositorId | R | int | Идентификатор залогодателя | Id клиента-залогодателя | |
| document | R | string | Документ | "" | |
| comment | R | string | Подробное описание | "" | |
| Стоимость | assessedValue | R | float | Оценочная стоимость | 0 |
| hypothecationValue | R | float | Залоговая стоимость | 0 | |
| Свойства | collateralProperties | R | collection | Свойства залога | [] |
Пример запроса
POST /bs-core/main/collaterals/properties/init/collateral-type-id/1017549{
"name": null,
"collateralTypeId": null,
"depositorId": null,
"document": "",
"comment": "",
"assessedValue": 0,
"hypothecationValue": 0,
"collateralProperties": []
}Пример успешного ответа
Метод возвращает JSON-объект — шаблон залога, с формированным идентификатором его свойств (collateralPropertyTypeId) и соответствующие поля. Шаблон используется для формирования тела запроса при создании или редактировании залога.
{
"name": null,
"collateralTypeId": 1017549,
"depositorId": null,
"document": "",
"comment": "",
"assessedValue": 0.0,
"hypothecationValue": 0.0,
"loanValue": 0.0,
"saleCode": "",
"saleBasis": "",
"tags": null,
"locationCityId": null,
"creationDate": null,
"collateralProperties": [
{
"collateralPropertyTypeId": 1018511,
"value": null,
"valueCustomDictId": null,
"orderId": 0
}
]
}Сохраните полученный ответ — он будет использован при создании залога на Шаге 5.
Шаг 3: Получение элементов справочника «Типы залогов» и их редактирование
Далее необходимо получить данные типа залога (из справочника), созданного на предыдущих этапах, и скорректировать его свойства.
Методы:
GET /bs-core/dicts/collateral-types/{id}PUT /bs-core/dicts/collateral-types/{id}
Описание: Тело PUT-запроса формируется на основе ответа GET /bs-core/dicts/collateral-types/{id}. В нём корректируется коллекция "collateralPropertyTypes": обновляются значения существующих свойств, либо добавляются/удаляются элементы при изменении структуры типа залога.
Документация:
- Получить элемент справочника "Типы залогов" по ID
- Редактировать элемент справочника "Типы залогов" по ID
Параметры запроса
{id} (integer, обязательный) — уникальный идентификатор типа залога, созданного на Шаге 1.
Пример запроса GET
GET /bs-core/dicts/collateral-types/1017549Пример ответа GET:
{
"name": "Авто тест2",
"bureauCode": "5",
"collateralPropertyTypes": [
{
"name": null,
"required": false,
"visible": false,
"orderNo": 0,
"customDictCategory": "",
"type": "",
"valuePattern": null,
"valuePatternHint": null,
"id": 1018511
}
],
"active": true,
"priorityNumber": null,
"id": 1017549
}Пример запроса PUT:
На основе ответа редактируется Тело запроса PUT, при необходимости добавляем свойства залога или правим существующие:
PUT /bs-core/dicts/collateral-types/1017549{
"name": "Авто тест2",
"bureauCode": "5",
"collateralPropertyTypes": [
{
"name": "Модель авто",
"required": true,
"visible": true,
"orderNo": 0,
"customDictCategory": "",
"type": "",
"valuePattern": null,
"valuePatternHint": null,
"id": 1018511
}
],
"active": true,
"priorityNumber": null,
"id": 1017549
}| Группа полей | Параметр | Обязательность | Тип | Описание | Примечание |
|---|---|---|---|---|---|
| Основные | id | R | int | Идентификатор типа залога | 1017549 |
| name | R | string | Наименование типа залога | "Авто тест2" | |
| bureauCode | R | int | Код для бюро | "5" | |
| active | R | bool | Действующий (Да/Нет) | true | |
| priorityNumber | R | int | Номер свойства залога | null | |
| Свойства | collateralPropertiesTypes._.id | М | int | Идентификатор свойства типа залога | 1018511 |
| collateralPropertiesTypes._.name | М | string | Наименование свойства типа залога | "Модель авто" | |
| collateralPropertiesTypes._.required | М | bool | Значение обязательности свойства | true | |
| collateralPropertiesTypes._.visible | М | bool | Значение видимости свойств | true | |
| collateralPropertiesTypes._.orderNo | R | int | Номер свойства залога | 0 |
Примечание: Добавлены поля valuePattern и valuePatternHint в collateralPropertyType для поиска залога по value, для корректной отработки метода поиска залога по значению его поля POST /main/collaterals/find-by-property-value.
Тело запроса для поиска:
{
"collateralPropertyTypeId": 123,
"value": "abc"
}Возвращает список collaterals, ответ идентичен методу GET /main/collaterals/{id}.
String valuePattern— Паттерн, которому должно соответствовать значение свойства залогаString valuePatternHint— Описание паттерна, которому должно соответствовать значение свойства залога
Паттерн — регулярное выражение.
Пример паттерна для VIN номера автомобиля, для осуществления поиска по данному номеру:
{
"name": "VIN код",
"required": false,
"visible": true,
"orderNo": 1,
"customDictCategory": null,
"type": "ChassisNumber",
"valuePattern": "^[WERTYUPASDFGHJKLZXCVBNM0-9]{17,17}$",
"valuePatternHint": "Строго 17 символов,большими латинскими буквами,I, O, Q не применимы",
"id": 1018315
}Шаг 4: Инициализация нового залога
Метод: GET /bs-core/main/collaterals/init
Описание: Перед созданием залога необходимо получить его "шаблон" с предзаполненными системными значениями, вызвав метод инициализации объекта залог.
Документация: Инициализация нового залога
Параметры запроса
Метод не принимает параметров.
Пример запроса
GET /bs-core/main/collaterals/initПример успешного ответа
Метод вернет JSON-объект залога. Сохраните его для использования на Шаге 5.
Шаг 5: Создание залога
Метод: POST /bs-core/main/collaterals
Описание: На этом шаге создается постоянная запись залога в системе.
Документация: Создание нового залога
Параметры запроса
Сформируйте объект залога на основе данных, полученных в Шаге 4 GET /bs-core/main/collaterals/init.
Важно
Для создания залога требуется заполнить обязательные поля, указанные в таблице ниже.
| Группа полей | Параметр | Обязательность | Тип | Описание | Примечание |
|---|---|---|---|---|---|
| Основные | id | R | int | Идентификатор Залога | При создании залога null, при сохранении присваивается автоматически идентификатор |
| name | R | string | Наименование залога | "Залог Тестовый" | |
| collateralTypeId | R | int | Идентификатор типа залога | Указывается из предварительно заполненного справочника (см Шаг 1) | |
| depositorId | R | int | Идентификатор залогодателя | Id клиента – залогодателя, идентификатор созданного клиента в системе | |
| document | R | string | Наименование договора | "" | |
| comment | R | string | Подробное описание | "" | |
| Стоимость | assessedValue | R | float | Оценочная стоимость | 25000.0 |
| hypothecationValue | R | float | Залоговая стоимость | 100000.0 | |
| loanValue | R | float | Ссудная стоимость | 0.0 | |
| Реализация | saleCode | R | string | Код залога для реализации | "" |
| saleBasis | R | string | Основание для реализации | "" | |
| Свойства | collateralProperties | R | collection | Свойства залога | Заполняется, если необходимо в дальнейшем применять свойства залогов |
| collateralProperties._.id | М | int | Идентификатор свойства залога | ||
| collateralProperties._.collateralPropertyTypeId | М | int | Идентификатор свойства типа залога | 1018511 (из Шага 2) | |
| collateralProperties._.value | М | string | Значение | "202020" | |
| collateralProperties._.orderId | М | int | Идентификатор порядкового номера | 0 |
Пример запроса
POST /bs-core/main/collaterals{
"name": "Залог Тестовый", // Наименование залога
"collateralTypeId": 1017549, // Идентификатор типа залога (из Шага 1)
"depositorId": 328, // Идентификатор залогодателя (Id клиента)
"document": "", // Наименование договора
"comment": "", // Подробное описание
"assessedValue": 25000.0, // Оценочная стоимость
"hypothecationValue": 100000.0, // Залоговая стоимость
"loanValue": 0.0, // Ссудная стоимость
"saleCode": "", // Код залога для реализации
"saleBasis": "", // Основание для реализации
"tags": null, // Теги залога
"locationCityId": null, // Идентификатор города расположения
"creationDate": null, // Дата создания
"collateralProperties": [
{
"collateralPropertyTypeId": 1018511, // Идентификатор свойства типа залога (из Шага 2)
"value": "202020", // Значение свойства
"valueCustomDictId": null, // Идентификатор пользовательского справочника
"orderId": 0 // Порядковый номер
}
]
}Пример успешного ответа
Метод вернет JSON-объект сохраненного залога в системе, с заполненными идентификаторами collateralsId и collateralProperties.
{
"name": "Залог Тестовый",
"collateralTypeId": 1017549,
"depositorId": 328,
"document": "",
"comment": "",
"assessedValue": 25000.0,
"hypothecationValue": 100000.0,
"loanValue": 0.0,
"saleCode": "",
"saleBasis": "",
"tags": null,
"locationCityId": null,
"creationDate": 1764099589148,
"collateralProperties": [
{
"collateralPropertyTypeId": 1018511,
"value": "202020",
"valueCustomDictId": null,
"orderId": 0,
"id": 1189
}
],
"id": 928,
"uid": null
}Примечание: private String UID — Уникальный номер залога с типом Гарантия/Поручительство — поле заполняется только для залогов с типом Поручительство/Гарантия, для остальных типов залога это поле всегда остается null.
Сохраните id залога (значение поля "id") — он понадобится для назначения залога к заявке на Шаге 6.
Шаг 6: Назначение залога к заявке на займ
Метод: GET /bs-core/main/loan-apps/{id} — Получение заявки на займ по ID.
Метод: PUT /bs-core/main/loan-apps/{id} — Обновление заявки на займ
Описание: Заполняем идентификатор созданного залога в параметре collateralIds.
Документация:
- Получение заявки на займ по ID
- Редактирование существующей заявки на займ
- См. документацию: «Описание бизнес-процесса: Создание клиента и заявки с автоматическим созданием лида и проверкой (СПР)».
Параметры запроса
{id} (integer, обязательный) — уникальный идентификатор заявки на займ.
Пример запроса GET
GET /bs-core/main/loan-apps/12345Пример ответа GET:
{
"id": 12345,
"name": "LA-2025-001234",
"clientId": 39208,
"collateralIds": []
// ... остальные поля заявки
}Пример запроса PUT:
PUT /bs-core/main/loan-apps/12345{
"collateralIds": [928] // Идентификатор созданного залога (из Шага 5)
}Пример успешного ответа
Метод вернет обновленный объект заявки с заполненным массивом collateralIds.
Обработка ошибок
Если вы столкнулись с ошибками при создании залога, вот наиболее вероятные причины:
| Код ошибки | Причина |
|---|---|
| METADATA__EMPTY_REQUIRED_FIELD | Не заполнено одно из обязательных полей (name, collateralTypeId, depositorId и т.д.) |
| NO_COLLATERAL_TYPE_ERROR | Не указан или неверно указан тип залога |
| NO_DEPOSITOR_ERROR | Не указан идентификатор залогодателя |
| INVALID_COLLATERAL_PROPERTY_ERROR | Неверно заполнены свойства залога |
Возможное решение: Убедитесь, что все обязательные поля заполнены корректно, и идентификаторы типов залогов и клиентов существуют в системе.
Дополнительная информация
Работа с тегами залогов
По залогу добавлены все категории (теги), к которым относится товар. К сущности collateral добавлен параметр tags (массив string).
Методы для получения залогов по тегам:
GET /main/collaterals/tags-list— Полный список теговGET /main/collaterals/search-by-tags/:tags— поиск по тегам (ищет залог по наличию хотя бы одного тега)- Параметры:
tags— теги через запятую like=trueпозволяет искать по неполному соответствию
- Параметры:
GET /main/collaterals/filter-by-tags/:tags— фильтр по тегам (у залога должны быть все теги из списка)