Настоящий документ представляет собой руководство для разработчиков со стороны банковского сервиса/CRM - поставщика лидов, ответственных за подготовку банковской системы/CRM к интеграции с системой Goodfin.
Доступ к документации с описанием типов и методов API
Базовое описание типов AddLead, CommonResponse и эндпоинта /ad/v1/external см. в https://sandbox.goodfin.ru/docs/shb-open-api/v1/index.html.
ПРИМЕЧАНИЕ
В песочнице (https://sandbox.goodfin.ru) доступны методы только для обучения работе со сделками. По лидам методы в песочнице не реализованы, имеется только описание типов в документации.
Краткое описание возможностей
- Система Goodfin предоставляет возможность банковским системам и CRM передавать лиды для их последующей обработки и отправки заявок в банки-партнеры на получение банковских продуктов. Для этого требуется согласно предлагаемой API спецификации выполнить доработку системы.
- Требования к набору обязательных полей в составе лида минимален, поэтому поставщик лидов может выбрать для себя желаемый объем передаваемой информации в Goodfin.
- Поставщик лидов может определить целевую аудиторию - получателей лидов в системе Goodfin:
Если в системе поставщика лидов добавить возможность клиенту отправлять свою заявку в Goodfin как лид, то лид будет отображен в личной кабинете клиента. Если клиент не зарегистрирован в системе, то ему будет отправлено приглашение на регистрацию в Goodfin, после выполнения которой клиент сможет обработать свой лид.
Если в системе поставщика лидов добавить возможность агенту отправлять карточку клиента/клиентов в Goodfin как лиды, то они будет доступны в личном кабинете агента на Goodfin.
Если инициатором отправки лидов будет сама система - поставщик лидов, то есть возможность указать правило обработки лида в Goodfin, а именно перечислить те банки, в которые могут быть отправлены заявки в ходе обработки лидов в системе Goodfin.
- Поставщики лидов смогут получать аналитику по результатам обработки лидов в Goodfin (пока не реализовано, идет сбор требований).
Краткое описание стадий работ для интеграции с действующей системой Goodfin
I. Для начала интеграционного взаимодействия поставщика лидов с системой Goodfin проводятся работы силами разработчиков поставщика лидов по поддержке API, предоставленного системой Goodfin. Cм. в API документации описание эндпоинта /ad/v1/external/openapi/in, а именно тип AddLead для подготовки и отправки лидов, тип CommonResponse для получения асинхронного ответа от Goodfin по результату получения лида с "SUCCESS" или "ERROR"). Также примеры сформированных лидов для передачи в Goodfin показаны в Примеры структуры передаваемого лида.
Если требуется обрабатывать изменение статусов заявок, созданных по лиду, то см. тип LeadDealApplicationStatusChanged в https://sandbox.goodfin.ru/docs/bl-open-api/v1/index.html и и пример сообщения ниже:
.
II. Далее для начала взаимодействия поставщику лидов передается логин и секрет. Эти данные должны использоваться поставщиком лидов для получения токена, чтобы поставщик лидов как система мог авторизоваться перед Goodfin как системой.
В api документации можно посмотреть метод /api/v1/oauth/token. Подробнее см. стандарт jwt.io по правилам получения и "времени жизни" токена.
III. Далее, если поставщик лидов будет передавать в Goodfin документы клиента в составе лида, то требуется предоставить системе Goodfin настройки, с помощью которых система Goodfin будет авторизовываться перед хранилищем документов поставщика лидов, чтобы иметь возможность скачать документы (см. в API описание эндпоинта /leadprovider/documentdownloadsettings/update). Ссылка для скачивания документа(ов) или ссылка для запроса конечного URL для скачивания передаётся в составе лида (см. в API документации типы Lead и LeadDocument).
IV. Отчет по результатам обработки лидов (частота, формат, объемы данных, метод передачи) согласуется с поставщиком лидов дополнительно.
Краткое описание стадий работ для предварительного тестирования интеграции в песочнице
Вы можете самостоятельно проверить, как будет выглядеть ваши лиды в системе Goodfin. Для этого вы можете воспользоваться тестовым окружением песочницы https://sandbox.goodfin.ru/.
Вы можете импортировать проект в Postman для тестирования:
окружение: sandbox-leads.postman_environment.json
коллекция: SANDBOX-LEADS.postman_collection.json
Порядок действий
- Зарегистрируйте тестового поставщика лидов в песочнице с помощью метода /api/v1/sandbox/registerleadprovider. Обратите внимание:
- В теле передается пара ИНН/ОГРН (для генерации можно использовать ресурс http://mellarius.ru/random-inn), на основании которой в песочнице создается тестовый агент.
- При отправке лидов типа agentLead вы должны использовать эту пару ИНН/ОГРН в теле передаваемого лида, а именно в объекте "agent". Так система узнает, какому агенту адресован лид.
- Метод выполнить один раз и запомнить значения полученной пары ключей "serviceSystemName" и "password".
- Значение ключа "serviceSystemName" с добавленным префиксом cc_ (англ.) используйте как логин для входа в песочницу и проверки отправленных лидов. Например, в ответе вы получили {"serviceSystemName": "J91nDdRWAz", "password": "RPTxt3jwsK"}, тогда для входа в песочницу и просмотра со стороны тестового агента в качестве логина использовать cc_J91nDdRWAz, в качестве пароля RPTxt3jwsK.
- Также значения полученной пары ключей "serviceSystemName" и "password" используются при генерации токена в методе /api/v1/oauth/token.
- Для получения/обновление токена используйте метод /api/v1/oauth/token.
- Чтобы получать от Goodfin сообщения об успешном/неуспешном приеме лида, смену статусов по заявке, созданной на основании лида, используйте метод /ad/external/integrationendpoint/update, в котором сообщите ваш ендпоинт, куда Goodfin будет слать ответные сообщения. Обратите внимание:
- Ендпоинт должен быть виден "снаружи", чтобы при тестировании можно было получать сообщения от песочницы Goodfin по результату приема лидов.
- Если в составе лидов отправляется информация о прикрепленных документах, то используйте метод /api/v1/leadprovider/documentdownloadsettings/update для передачи информации по правилам аутентификации для скачивания документов.
- Для отправки лидов используйте метод /ad/v1/external/openapi/in c "payloadType":"AddLead". Обратите внимание:
- В объекте "lead" ключ "id": UUID должен быть уникальный.
- При попытке отправить два лида с одним и тем же id все, кроме первого полученного, будут игнорироваться.
- В качестве значения ключа "originator" установить значение ключа "serviceSystemName", полученное при выполнении метода /api/v1/sandbox/registerleadprovider.
- В качестве значения ключа "receiver" всегда устанавливайте "Shb".
- Если отправляете лид типа agentLead, то в объекте "agent" укажите пару ИНН/ОГРН, которую указывали при вызове метода /api/v1/sandbox/registerleadprovider. Примечание: при интеграции с действующей системой Goodfin вы должны будете передавать реальные ИНН/ОГРН того агента, которому адресован агентский лид.
- Проверить получение лида в песочнице https://sandbox.goodfin.ru/. Для этого войти с помощью логина/пароля (см. пункт 1.d). О работе с лидами можно почитать в статье Как обработать лид.