Личный кабинет агента банка 2.0: документация API
Базовая информация
Аутентификация и авторизация
Все запросы, кроме запросов, связанных с регистрацией пользователя и восстановлением пароля, должны включать в себя заголовки HTTP Basic Authorization. В качестве логина и пароля используются E-mail и пароль пользователя.
Подстановочные шаблоны
- {{app_host}}: хост и порт приложения
- {{user_id}}: идентификатор Пользователя
- {{lead_id}}: идентификатор Лида
- {{payment_request_id}}: идентификатор Запроса на вывод
Регистрация в системе
Эта группа запросов не требует аутентификации.
Регистрация Агента
В ответ на этот запрос ЛК возвращает пароль новой учётной записи. Задача Front-end — безопасно передать этот пароль пользователю.
Запрос:
POST http://{{app_host}}/api/v2/users
{
"email": "test@regberry.ru"
}
Ответ:
{
"id": 1,
"password": "3#XHpA%T$o#q#I%n6F2w1x"
}
Сброс пароля
Эта группа запросов не требует аутентификации.
Сброс пароля представляет собой двухэтапный процесс:
- Сначала ЛК формирует код подтверждения, который необходимо переслать пользователю.
- Затем Front-end отправляет в ЛК полученный пользователем код, чтобы сгенерировать новый пароль. Задача Front-end — безопасно передать новый пароль пользователю.
Сброс пароля, этап 1 (формирование кода подтвеждения)
Запрос:
POST http://{{app_host}}/api/v2/users/reset-password
{
"email": "test@regberry.ru"
}
Ответ:
{
"confirmation_code": "Oufu8u31y1y6L4PfwAo5UVHAF1gKrEMf"
}
Сброс пароля, этап 2 (проверка кода подтвеждения)
Запрос:
POST http://{{app_host}}/api/v2/users/reset-password/confirm
{
"email": "test@regberry.ru",
"confirmation_code": "T2mGMaiK8vgm0D3WhCUC929rB5rspLAu"
}
Ответ:
{
"password": "c%%G0#$q69w$4#UMaQrhJQ"
}
Работа с учётной записью
Загрузка текущего пользователя
Запрос:
GET http://{{app_host}}/api/v2/users/me
Ответ:
{
"agent_type": "PERSON",
"agent_agreement_file": "/docs/61fe0c53-82a6-43e4-92d1-c98497a39104.docx",
"id": 1,
"created": "2022-08-21T16:49:06.200618",
"status": "ACTIVE",
"email": "test@regberry.ru",
"employees": [
{
"commission_rate": 75,
"id": 2,
"email": "test2@regberry.ru",
"status": "ACTIVE",
"name": "Петров Петр Геннадьевич",
"employer": 1
}
]
}
Создание Агента-физлица
Запрос:
POST http://{{app_host}}/api/v2/users/{{user_id}}/person
{
"person": {
"name": "Заболотский Сергей Петрович",
"birthday": "1980-04-12",
"phone": "9051234567",
"passport": {
"serial": "1234",
"number": "999777",
"date": "2019-05-01",
"issuer": "РОВД Москвы"
},
"address": {
"city": "Москва",
"legal": "Москва, 1",
"postal": "Москва, 2"
},
"inn": "495505872258",
"snils": "38096549730"
},
"bank_details": {
"name": "Московский банк Сбербанка России (ПАО)",
"bik": "044525225",
"correspondent_account": "30101810400000000225",
"bank_account": "40702810138170109674",
"inn": "7733574418",
"kpp": "770401001"
}
}
Редактирование Агента-физлица
Запрос:
PUT http://{{app_host}}/api/v2/users/{{user_id}}/person
{
"person": {
"name": "Заболотский Сергей Петрович",
"birthday": "1980-04-12",
"phone": "9051234567",
"passport": {
"serial": "1234",
"number": "999777",
"date": "2019-05-01",
"issuer": "РОВД Москвы"
},
"address": {
"city": "Москва",
"legal": "Москва, 1",
"postal": "Москва, 2"
},
"inn": "495505872258",
"snils": "38096549730"
},
"bank_details": {
"name": "Московский банк Сбербанка России (ПАО)",
"bik": "044525225",
"correspondent_account": "30101810400000000225",
"bank_account": "40702810138170109674",
"inn": "7733574418",
"kpp": "770401001"
}
}
Загрузка Агента-физлица
Запрос:
http://{{app_host}}/api/v2/users/{{user_id}}/person
Ответ:
{
"person": {
"name": "Заболотский Сергей Петрович",
"birthday": "1980-04-12",
"phone": "9051234567",
"passport": {
"serial": "1234",
"number": "999777",
"date": "2019-05-01",
"issuer": "РОВД Москвы"
},
"address": {
"city": "Москва",
"legal": "Москва, 1",
"postal": "Москва, 2"
},
"inn": "495505872258",
"snils": "38096549730"
},
"bank_details": {
"name": "Московский банк Сбербанка России (ПАО)",
"bik": "044525225",
"correspondent_account": "30101810400000000225",
"bank_account": "40702810138170109674",
"inn": "7733574418",
"kpp": "770401001"
}
}
Создание Агента-ИП
Допустимые значения поля company.tax_system
:
- usn
- osn
Запрос:
POST http://{{app_host}}/api/v2/users/{{user_id}}/ip
{
"company": {
"title": "ИП Иванов Сергей Петрович",
"registration_date": "2021-04-12",
"tax_system": "usn",
"inn": "870300371468",
"ogrn": "311870619600012",
"address": {
"city": "Москва",
"legal": "Москва, 1",
"postal": "Москва, 2"
},
"ceo": {
"name_full_nominative": "Иванов Сергей Петрович",
"name_full_genitive": "Иванова Сергея Петровича",
"name_short": "Иванов С.П.",
"phone": "9011234567"
}
},
"bank_details": {
"name": "Московский банк Сбербанка России (ПАО)",
"bik": "044525225",
"correspondent_account": "30101810400000000225",
"bank_account": "40702810138170109674",
"inn": "7733574418",
"kpp": "770401001"
}
}
Редактирование Агента-ИП
Допустимые значения поля company.tax_system
:
- usn
- osn
Запрос:
PUT http://{{app_host}}/api/v2/users/{{user_id}}/ip
{
"company": {
"title": "ИП Иванов Сергей Петрович",
"registration_date": "2021-04-12",
"tax_system": "usn",
"inn": "870300371468",
"ogrn": "311870619600012",
"address": {
"city": "Москва",
"legal": "Москва, 1",
"postal": "Москва, 2"
},
"ceo": {
"name_full_nominative": "Иванов Сергей Петрович",
"name_full_genitive": "Иванова Сергея Петровича",
"name_short": "Иванов С.П.",
"phone": "9011234567"
}
},
"bank_details": {
"name": "Московский банк Сбербанка России (ПАО)",
"bik": "044525225",
"correspondent_account": "30101810400000000225",
"bank_account": "40702810138170109674",
"inn": "7733574418",
"kpp": "770401001"
}
}
Загрузка Агента-ИП
Запрос:
http://{{app_host}}/api/v2/users/{{user_id}}/ip
Ответ:
{
"company": {
"title": "ИП Иванов Сергей Петрович",
"registration_date": "2021-04-12",
"tax_system": "usn",
"inn": "870300371468",
"ogrn": "311870619600012",
"address": {
"city": "Москва",
"legal": "Москва, 1",
"postal": "Москва, 2"
},
"ceo": {
"name_full_nominative": "Иванов Сергей Петрович",
"name_full_genitive": "Иванова Сергея Петровича",
"name_short": "Иванов С.П.",
"phone": "9011234567"
}
},
"bank_details": {
"name": "Московский банк Сбербанка России (ПАО)",
"bik": "044525225",
"correspondent_account": "30101810400000000225",
"bank_account": "40702810138170109674",
"inn": "7733574418",
"kpp": "770401001"
}
}
Создание Агента-ООО
Допустимые значения поля company.tax_system
:
- usn
- osn
Запрос:
POST http://{{app_host}}/api/v2/users/{{user_id}}/ooo
{
"company": {
"title": "ООО Ромашка",
"registration_date": "2021-04-12",
"tax_system": "osn",
"inn": "7735560386",
"ogrn": "1097746328360",
"kpp": "773501001",
"address": {
"city": "Москва",
"legal": "Москва, 1",
"postal": "Москва, 2"
},
"ceo": {
"name_full_nominative": "Иванов Сергей Петрович",
"name_full_genitive": "Иванова Сергея Петровича",
"name_short": "Иванов С.П.",
"phone": "9011234567",
"position_nominative": "Директор",
"position_genitive": "Директорa",
"basis_nominative": "Устав",
"basis_genitive": "Устава"
}
},
"bank_details": {
"name": "Московский банк Сбербанка России (ПАО)",
"bik": "044525225",
"correspondent_account": "30101810400000000225",
"bank_account": "40702810138170109674",
"inn": "7733574418",
"kpp": "770401001"
}
}
Редактирование Агента-ООО
Допустимые значения поля company.tax_system
:
- usn
- osn
Запрос:
PUT http://{{app_host}}/api/v2/users/{{user_id}}/ooo
{
"company": {
"title": "ИП Иванов Сергей Петрович",
"registration_date": "2021-04-12",
"tax_system": "usn",
"inn": "870300371468",
"ogrn": "311870619600012",
"address": {
"city": "Москва",
"legal": "Москва, 1",
"postal": "Москва, 2"
},
"ceo": {
"name_full_nominative": "Иванов Сергей Петрович",
"name_full_genitive": "Иванова Сергея Петровича",
"name_short": "Иванов С.П.",
"phone": "9011234567"
}
},
"bank_details": {
"name": "Московский банк Сбербанка России (ПАО)",
"bik": "044525225",
"correspondent_account": "30101810400000000225",
"bank_account": "40702810138170109674",
"inn": "7733574418",
"kpp": "770401001"
}
}
Загрузка Агента-ООО
Запрос:
http://{{app_host}}/api/v2/users/{{user_id}}/ooo
Ответ:
{
"company": {
"title": "ООО Ромашка",
"registration_date": "2021-04-12",
"tax_system": "osn",
"inn": "7735560386",
"ogrn": "1097746328360",
"kpp": "773501001",
"address": {
"city": "Москва",
"legal": "Москва, 1",
"postal": "Москва, 2"
},
"ceo": {
"name_full_nominative": "Иванов Сергей Петрович",
"name_full_genitive": "Иванова Сергея Петровича",
"name_short": "Иванов С.П.",
"phone": "9011234567",
"position_nominative": "Директор",
"position_genitive": "Директорa",
"basis_nominative": "Устав",
"basis_genitive": "Устава"
}
},
"bank_details": {
"name": "Московский банк Сбербанка России (ПАО)",
"bik": "044525225",
"correspondent_account": "30101810400000000225",
"bank_account": "40702810138170109674",
"inn": "7733574418",
"kpp": "770401001"
}
}
Отправка Агента на модерацию
Агент выполняет этот запрос после того, как заполнит реквизиты физического лица, ИП или ООО.
Допустимые значения поля agent_type
:
- PERSON
- IP
- OOO
Запрос:
POST http://{{app_host}}/api/v2/users/request-approval
{
"agent_type": "PERSON"
}
Модерация Агентов
Запросы, указанные в этом разделе, может выполнять только Менеджер.
Список пользователей
Запрос:
GET http://{{app_host}}/api/v2/users
Ответ:
[
{
"agent_type": "OOO",
"agent_agreement_file": "/docs/a3ec9fc4-163a-4fda-9ce4-6f5552a708ef.docx",
"commission_rate": 100,
"employer_user_account_id": null,
"id": 3,
"created": "2022-08-26T06:28:38.759892",
"status": "ACTIVE",
"email": "test3@regberry.ru",
"name": null
},
{
"agent_type": "IP",
"agent_agreement_file": "/docs/ceda4425-1a26-41e6-9854-d87089a125d2.docx",
"commission_rate": 100,
"employer_user_account_id": null,
"id": 4,
"created": "2022-08-23T06:48:03.375243",
"status": "NEW",
"email": "test4@regberry.ru",
"name": null
}
]
Модерация: отклонение Пользователя
Запрос:
POST http://{{app_host}}/api/v2/users/{{user_id}}/approval/decline
Модерация: подтверждение Пользователя
Запрос:
POST http://{{app_host}}/api/v2/users/{{user_id}}/approval/approve
Модерация: отклонение документов
Запрос:
POST http://{{app_host}}/api/v2/users/{{user_id}}/signed-documents/decline
Модерация: подтверждение документов
Запрос:
POST http://{{app_host}}/api/v2/users/{{user_id}}/signed-documents/approve
Модерация: "обнуление" статуса Пользователя
Запрос:
POST http://{{app_host}}/api/v2/users/{{user_id}}/reset
Блокировка Пользователя
Запрос:
POST http://{{app_host}}/api/v2/users/{{user_id}}/block
Разблокировка Пользователя
При разблокировке:
- статус Агента сбрасывается на "Новый"
- статус Сотрудника сбрасывается на "Активный"
Запрос:
POST http://{{app_host}}/api/v2/users/{{user_id}}/unblock
Работа Агентов с Сотрудниками
Запросы, указанные в этом разделе, может выполнять только Агент.
Создание Сотрудника
Запрос:
POST http://{{app_host}}/api/v2/employees
{
"email": "test1@regberry.ru",
"name": "Иванов Петр Геннадьевич",
"commission_rate": 75
}
Ответ:
{
"id": 2,
"password": "eY$EQe#8x9$%#Gg3tyH3#K"
}
Редактирование Сотрудника
Запрос:
PUT http://{{app_host}}/api/v2/employees/{{user_id}}
{
"email": "test1@regberry.ru",
"name": "Иванов Петр Геннадьевич",
"commission_rate": 75
}
Загрузка Сотрудника
Запрос:
GET http://{{app_host}}/api/v2/employees/{{user_id}}
Ответ:
{
"commission_rate": 75,
"email": "test1@regberry.ru",
"status": "ACTIVE",
"name": "Иванов Петр Геннадьевич",
"employer": 1
}
Список Сотрудников
Запрос:
GET http://{{app_host}}/api/v2/employees
Ответ:
[
{
"commission_rate": 75,
"id": 2,
"email": "test1@regberry.ru",
"status": "ACTIVE",
"name": "Петров Петр Геннадьевич",
"employer": 1
},
{
"commission_rate": 80,
"id": 3,
"email": "test2@regberry.ru",
"status": "ACTIVE",
"name": "Иванов Петр Геннадьевич",
"employer": 1
}
]
]
Блокировка Сотрудника
Запрос:
POST http://{{app_host}}/api/v2/employees/{{user_id}}/block
Разблокировка Сотрудника
Запрос:
POST http://{{app_host}}/api/v2/employees/{{user_id}}/unblock
Работа с лидами
Запросы, указанные в этом разделе, могут выполнять как Агенты, так и их Сотрудники.
Финансовые значения хранятся в копейках.
Список банковских предложений
Запрос:
GET http://{{app_host}}/api/v2/bank-offers
Ответ:
[
{
"bank_title": "tochka",
"commission": 350000
},
{
"bank_title": "tinkoff",
"commission": 450000
},
{
"bank_title": "open",
"commission": 350000
}
]
Создание Лида
Запрос:
POST http://{{app_host}}/api/v2/leads
{
"company": {
"type": "OOO",
"title": "ООО Одуванчик",
"inn": "9042635351",
"ogrn": "1097746328360"
},
"contact_person": {
"name": "Сергей",
"email": "test@regberry.ru",
"phone": "4997558596"
},
"city": "Москва",
"comment": "Звонить по вторникам",
"banks": [
"open",
"tinkoff",
"tochka"
]
}
Ответ:
{
"id": 1
}
Загрузка Лида
Запрос:
GET http://{{app_host}}/api/v2/leads/{{lead_id}}
Ответ:
{
"contact_person": {
"name": "Сергей",
"email": "test@regberry.ru",
"phone": "4997558596"
},
"created": "2022-08-30T12:39:45.169285",
"company": {
"type": "OOO",
"title": "ООО Одуванчик",
"inn": "9042635351",
"ogrn": "1097746328360"
},
"city": "Москва",
"comment": "Москва",
"items": [
{
"bank_title": "tinkoff",
"bank_lead_id": "5efd18d9-9a83-4e08-8616-743f83adb5da",
"bank_status": "PROCESSING",
"commission_rate": 100,
"id": 56,
"commission": 450000
},
{
"bank_title": "open",
"bank_lead_id": "ecf4c512-3137-47af-88df-7747bd6ba7a8",
"bank_status": "PROCESSING",
"commission_rate": 100,
"id": 57,
"commission": 350000
}
]
}
Список Лидов
Запрос:
GET http://{{app_host}}/api/v2/leads
Ответ:
[
{
"user_account_id": 1,
"contact_person": {
"name": "Сергей",
"email": "test@regberry.ru",
"phone": "4997558596"
},
"id": 27,
"created": "2022-08-30T12:39:45.169285",
"company": {
"type": "OOO",
"title": "ООО Одуванчик",
"inn": "9042635351",
"ogrn": "1097746328360"
},
"city": "Москва",
"comment": "Москва",
"items": [
{
"bank_title": "tinkoff",
"bank_lead_id": "5efd18d9-9a83-4e08-8616-743f83adb5da",
"bank_status": "PROCESSING",
"commission_rate": 100,
"id": 56,
"commission": 450000
},
{
"bank_title": "open",
"bank_lead_id": "ecf4c512-3137-47af-88df-7747bd6ba7a8",
"bank_status": "PROCESSING",
"commission_rate": 100,
"id": 57,
"commission": 350000
}
]
}
]
Биллинг: Заявки
Список Заявок
Запрос:
GET http://{{app_host}}/api/v2/billing/lead-items
Ответ:
[
{
"lead_id": 1,
"user_account_id": 1,
"contact_person": {
"name": "Сергей",
"email": "test@regberry.ru",
"phone": "4997558596"
},
"lead_item_id": 56,
"bank_title": "tinkoff",
"bank_lead_id": "5efd18d9-9a83-4e08-8616-743f83adb5da",
"bank_status": "COMPLETE",
"commission_rate": 100,
"payment_request_id": null,
"payment_request_status": null,
"created": "2022-08-30T12:39:45.169285",
"company": {
"type": "OOO",
"title": "ООО Одуванчик",
"inn": "9042635351",
"ogrn": "1097746328360"
},
"commission": 450000
},
{
"lead_id": 1,
"user_account_id": 1,
"contact_person": {
"name": "Сергей",
"email": "test@regberry.ru",
"phone": "4997558596"
},
"lead_item_id": 57,
"bank_title": "open",
"bank_lead_id": "ecf4c512-3137-47af-88df-7747bd6ba7a8",
"bank_status": "COMPLETE",
"commission_rate": 100,
"payment_request_id": null,
"payment_request_status": null,
"created": "2022-08-30T12:39:45.169285",
"company": {
"type": "OOO",
"title": "ООО Одуванчик",
"inn": "9042635351",
"ogrn": "1097746328360"
},
"commission": 350000
}
]
Изменение банковского статуса Заявок
Этот запрос может выполнять только Менеджер.
Допустимые значения поля bank_status
:
- COMPLETE
- PAID
Запрос:
POST http://{{app_host}}/api/v2/billing/lead-items
{
"bank_status": "PAID",
"lead_item_ids": [94, 95]
}
Биллинг: Запросы на вывод
Создание Запроса на вывод
Запрос:
POST http://{{app_host}}/api/v2/billing/payment-requests
{
"lead_item_ids": [94,95]
}
Ответ:
{
"id": 1
}
Список Запросов на вывод
Запрос:
GET http://{{app_host}}/api/v2/billing/payment-requests
Ответ:
[
{
"user_account_id": 1,
"report_file": "/docs/c15c1378-cb52-45f6-b90f-ec5a02a7d8ba.xlsx",
"declension_reason": null,
"id": 1,
"created": "2022-08-28T16:26:20.033741",
"status": "COMPLETE",
"amount": 1150000
}
]
Загрузка Запроса на вывод
Запрос:
GET http://{{app_host}}/api/v2/billing/payment-requests/{{payment_request_id}}
Ответ:
{
"report_file": "/docs/c15c1378-cb52-45f6-b90f-ec5a02a7d8ba.xlsx",
"declension_reason": null,
"lead_items": [
{
"lead_id": 20,
"user_account_id": 1,
"contact_person": {
"name": "Сергей",
"email": "test@regberry.ru",
"phone": "4997558596"
},
"lead_item_id": 39,
"bank_title": "tochka",
"bank_lead_id": "fe91994b-60ec-44f7-8558-1ee51a58517c",
"bank_status": "PAID",
"commission_rate": 100,
"payment_request_id": 7,
"payment_request_status": "COMPLETE",
"created": "2022-08-28T16:25:34.125264",
"company": {
"type": "OOO",
"title": "ООО Одуванчик",
"inn": "9042635351",
"ogrn": "1097746328360"
},
"commission": 350000
},
{
"lead_id": 20,
"user_account_id": 1,
"contact_person": {
"name": "Сергей",
"email": "test@regberry.ru",
"phone": "4997558596"
},
"lead_item_id": 40,
"bank_title": "tinkoff",
"bank_lead_id": "373eaba7-d5e7-49f4-8b96-2360785f74fb",
"bank_status": "PAID",
"commission_rate": 100,
"payment_request_id": 7,
"payment_request_status": "COMPLETE",
"created": "2022-08-28T16:25:34.125264",
"company": {
"type": "OOO",
"title": "ООО Одуванчик",
"inn": "9042635351",
"ogrn": "1097746328360"
},
"commission": 450000
},
{
"lead_id": 20,
"user_account_id": 1,
"contact_person": {
"name": "Сергей",
"email": "test@regberry.ru",
"phone": "4997558596"
},
"lead_item_id": 41,
"bank_title": "open",
"bank_lead_id": "59f1de90-9191-4aae-82db-16dbcdd86b58",
"bank_status": "PAID",
"commission_rate": 100,
"payment_request_id": 7,
"payment_request_status": "COMPLETE",
"created": "2022-08-28T16:25:34.125264",
"company": {
"type": "OOO",
"title": "ООО Одуванчик",
"inn": "9042635351",
"ogrn": "1097746328360"
},
"commission": 350000
}
],
"created": "2022-08-28T16:26:20.033741",
"status": "COMPLETE"
}
Модерация Запросов на вывод
Запросы, указанные в этом разделе, может выполнять только Менеджер.
Модерация: отклонение Запроса на вывод
Запрос:
POST http://{{app_host}}/api/v2/billing/payment-requests/{{payment_request_id}}/decline
Модерация: подтверждение Запроса на вывод
Запрос:
POST http://{{app_host}}/api/v2/billing/payment-requests/{{payment_request_id}}/approve