Page tree
Skip to end of metadata
Go to start of metadata

Настоящий документ представляет собой руководство для разработчиков со стороны банковского сервиса/CRM - поставщика лидов, ответственных за подготовку банковской системы/CRM к интеграции с системой Goodfin. 

Доступ к документации с описанием типов и методов API

Базовое описание типов AddLead, CommonResponse и эндпоинта /ad/v1/external см. в https://sandbox.goodfin.ru/docs/shb-open-api/v1/index.html.


ПРИМЕЧАНИЕ

В песочнице (https://sandbox.goodfin.ru) доступны методы только для обучения работе со сделками. По лидам методы в песочнице не реализованы, имеется только описание типов в документации.

Краткое описание возможностей

  1. Система Goodfin предоставляет возможность банковским системам и CRM передавать лиды для их последующей обработки и отправки заявок в банки-партнеры на получение банковских продуктов. Для этого требуется согласно предлагаемой API спецификации выполнить доработку системы.
  2. Требования к набору обязательных полей в составе лида минимален, поэтому поставщик лидов может выбрать для себя желаемый объем передаваемой информации в Goodfin.
  3. Поставщик лидов может определить целевую аудиторию - получателей лидов в системе Goodfin:
    1. Если в системе поставщика лидов добавить возможность клиенту отправлять свою заявку в Goodfin как лид, то лид будет отображен в личной кабинете клиента. Если клиент не зарегистрирован в системе, то ему будет отправлено приглашение на регистрацию в Goodfin, после выполнения которой клиент сможет обработать свой лид.

    2. Если в системе поставщика лидов добавить возможность агенту отправлять карточку клиента/клиентов в Goodfin как лиды, то они будет доступны в личном кабинете агента на Goodfin.

    3. Если инициатором отправки лидов будет сама система - поставщик лидов, то есть возможность указать правило обработки лида в Goodfin, а именно перечислить те банки, в которые могут быть отправлены заявки в ходе обработки лидов в системе Goodfin.

  4. Поставщики лидов смогут получать аналитику по результатам обработки лидов в 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 и  и пример сообщения ниже: 


 Нажмите, чтобы посмотреть пример сообщения
{
   "payloadType":"LeadDealApplicationStatusChanged",
   "originator":"Shb",
   "receiver":"test-lp1.io",
   "msgId":"8d778182-5067-4419-8207-a955dd1e111a",
   "msgDateTime":"2020-04-20T08:20:32.749514",
   "payload":{
      "lead":{
         "id":"cd08bc21-9b0c-4f84-b9d5-c9068ea989b3",
         "number":"10106",
         "deal":{
            "id":"46f3084a-cc99-4b1f-898b-4b31356d63ff",
            "createDateTime":"2020-04-17T11:53:28.031809",
            "dealApplication":{
               "id":"fc13db5f-8606-454c-8eb2-9fa84cc9cf03",
               "number":null,
               "createDateTime":"2020-04-17T11:53:28.031809",
               "serviceSysVal":"client2-shb.srvtests.com",
               "status":"REJECTED_BY_SERVICE",
               "serviceSysStatus":"22",
               "statusDateTime":"2020-04-20T08:20:32.664338"
            }
         },
         "responsibles":[{"email":"agent@agent.ru"}]
      }
   }
}


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


Порядок действий

  1. Зарегистрируйте тестового поставщика лидов в песочнице с помощью метода /api/v1/sandbox/registerleadprovider. Обратите внимание:
    1. В теле передается пара ИНН/ОГРН (для генерации можно использовать ресурс http://mellarius.ru/random-inn), на основании которой в песочнице создается тестовый агент. 
    2. При отправке лидов типа agentLead вы должны использовать эту пару ИНН/ОГРН в теле передаваемого лида, а именно в объекте "agent". Так система узнает, какому агенту адресован лид.
    3. Метод выполнить один раз и запомнить значения полученной пары ключей "serviceSystemName" и "password".
    4. Значение ключа "serviceSystemName" с добавленным префиксом cc_ (англ.) используйте как логин для входа в песочницу и проверки отправленных лидов. Например, в ответе вы получили {"serviceSystemName": "J91nDdRWAz", "password": "RPTxt3jwsK"}, тогда для входа в песочницу и просмотра со стороны тестового агента в качестве логина использовать cc_J91nDdRWAz, в качестве пароля RPTxt3jwsK.
    5. Также значения полученной пары ключей "serviceSystemName" и "password" используются при генерации токена в методе /api/v1/oauth/token.
  2. Для получения/обновление токена используйте метод /api/v1/oauth/token.
  3. Чтобы получать от Goodfin сообщения об успешном/неуспешном приеме лида, смену статусов по заявке, созданной на основании лида, используйте метод /ad/external/integrationendpoint/update, в котором сообщите ваш ендпоинт, куда Goodfin будет слать ответные сообщения. Обратите внимание:
    1. Ендпоинт должен быть виден "снаружи", чтобы при тестировании можно было получать сообщения от песочницы Goodfin по результату приема лидов.
  4. Если в составе лидов отправляется информация о прикрепленных документах, то используйте метод /api/v1/leadprovider/documentdownloadsettings/update для передачи информации по правилам аутентификации для скачивания документов.
  5. Для отправки лидов используйте метод /ad/v1/external/openapi/in c "payloadType":"AddLead". Обратите внимание:  
    1. В объекте "lead" ключ "id": UUID должен быть уникальный.
    2. При попытке отправить два лида с одним и тем же id все, кроме первого полученного, будут игнорироваться.  
    3. В качестве значения ключа "originator" установить значение ключа "serviceSystemName", полученное при выполнении метода /api/v1/sandbox/registerleadprovider.
    4. В качестве значения ключа "receiver" всегда устанавливайте "Shb".
    5. Если отправляете лид типа agentLead, то в объекте "agent" укажите пару ИНН/ОГРН, которую указывали при вызове метода /api/v1/sandbox/registerleadprovider. Примечание: при интеграции с действующей системой Goodfin вы должны будете передавать реальные ИНН/ОГРН того агента, которому адресован агентский лид.
  6. Проверить получение лида в песочнице https://sandbox.goodfin.ru/. Для этого войти с помощью логина/пароля (см. пункт 1.d). О работе с лидами можно почитать в статье Как обработать лид.
  • No labels