Назад

Интеграция и обмен данными с внешней CRM системой

11.06.2021
#Интеграции

Оглавление

1. Способы загрузки и обновления данных в Базис Недвижимость

    1.1. Загрузка помещений

    1.2. Загрузка сделок и клиентов

2. Способы получения данных из Базис Недвижимость

3. Сценарий обмена данными (ПРИМЕР)

4. Схема обмена данными с участием сайта

5. Часто задаваемые вопросы


Для чего нужна интеграция

Если у вас есть внешняя система и часть отделов продолжают работать в ней, а часть переходят на работу в системе Базис Недвижимость (БН), может возникнуть потребность в синхронизации данных между системами, в базовом сценарии это три основных пункта:

  • Данные по помещениям (площади, цена)
  • Данные по сделкам (статус, сумма, выбранное помещение)
  • Данные по участникам сделок (ФИО, телефон, паспортные данные)


Способы загрузки и обновления данных в Базис Недвижимость

Данные по помещениям

Есть три варианта по загрузке помещений (рекомендуем вариант 2):

1) Импорт из Excel (малая степень автоматизации, требует минимальное кол-во ресурсов от вашего отдела разработки) - вы можете создать в своей системе выгрузку помещений в файл Excel в требуемом формате, а затем загрузить этот файл в кабинете Базис Недвижимость.

Плюсы: 

+ Легко начать работать

+ Минимум разработки на вашей стороне

Минусы:

- Файл нужно формировать каждый раз заново и вручную загружать в БН

- Есть риск неверно сопоставить колонки при загрузке и "испортить данные" (придется загружать еще раз, чтобы исправить)

2) Импорт из фида  Рекомендуем!  (высокая степень автоматизации, средняя сложность разработки) - Создайте в своей системе автоматический Фид (ссылка на xml-файл, который формируется динамически из вашей базы данных) и укажите ссылку на него в кабинете БН, помещения будут загружены, а при повторной загрузке того же фида, данные будут обновляться, таким образом можно держать данные актуальными в обеих системах.

Описание фида для загрузки в Базис Недвижимость здесь: https://iflat.io/blog/17-basis-xml-feed

Плюсы: 

+ Данные приходят всегда в одном формате, что исключает человеческий фактор и появление ошибок

+ Минимум расхождений в данных. Один и тот же фид можно загружать каждый день, в нем всегда актуальные данные, а значит каждый день актуальные данные будут попадать и в Базис Недвижимость

+ Если у вас уже есть выгрузка квартир на Яндекс.Недвижимость, достаточно будет добавить к ней несколько полей, чтобы этот фид подошел и для Базис Недвижимость

Минусы:

- Потребуются ресурсы на вашей стороне для разработки такого фида

3) Создание и обновление объектов через методы API (самая высокая степень автоматизации, высокая сложность разработки) - используя наше Rest API, вы можете полностью создавать и контролировать всю структуру данных в Базис Недвижимость, добавлять дома/этажи/помещения, менять их свойства, удалять, любые действия.

Описание документации по API здесь: https://iflat.io/api/documentation

Плюсы: 

+ Полный контроль над данными 

Минусы:

- Потребуются большие ресурсы на вашей стороне для разработки подобной интеграции (вникнуть в структуру данных, написать функции по работе с каждым объектом)


Данные по сделкам и покупателям

Как и в случае с помещениями, есть три варианта, с теми же плюсами и минусами:

  1. Импорт из Excel (низкая автоматизация, минимум затрат ресурсов)
  2. Импорт из Фида (высокая автоматизация, среднее количество ресурсов) - описание формата фида https://iflat.io/blog/22-basis-deal-json-feed
  3. Прямая работа через API (высокая автоматизация, большое количество ресурсов)

Рекомендуем загружать данные по сделкам с помощью вариантов 2 или 3 , поскольку при импорте из Excel придется сначала загрузить сделки и ФИО участников, а затем, отдельным файлом, загрузить паспортные данные по каждому участнику, что усложняет процесс.

Как начать работу и загрузить данные подробно описано в статье Быстрый старт https://iflat.io/blog/12-get-started

Если вы используете amoCRM, интеграция по сделками и покупателям уже готова, подробнее здесь: https://iflat.io/blog/10-amocrm-widget


Способы получения данных из Базис Недвижимость

У вас может возникнуть потребность получать обратно, в свою учетную систему, какие-либо данные из Базис Недвижимость, такими данными могут быть, например:

  • Информация по появлению новой приемки, дата приемки
  • Статус проведенной приемки (успешно/с замечаниями)
  • Появление новой технической заявки на устранение замечаний
  • Появление наряда на работу
  • Отметка техзаявки или наряда как Выполнено
  • Изменение информации по помещению (статус квартиры)
  • Изменение данных покупателя (ФИО или паспортные данные)

Есть три варианта решения такой задачи:

1) По расписанию/запросу с вашей стороны - вы можете в любой момент забрать, например, список новых приемок или все технические заявки с помощью метода API, и дальше на своей стороне использовать полученные данные

2) Автоматический сигнал (Webhook) со стороны БН при наступлении события создания или изменения объекта - как только будет создана новая приемка или техзаявка, на ваш адрес сразу будет отправлена информация о них, это происходит в режиме реального времени. Подробнее о вебхуках здесь: https://iflat.io/blog/18-webhooks

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

Рекомендуем! В целях получения данных использовать вариант 1, по расписанию, например, раз в сутки забирать данные обо всех приемках и техзаявках за прошедший день. А при необходимости каких-либо действий в реальном времени, например, если вам нужно ставить менеджеру задачу в CRM при завершении приемки, использовать вебхук на изменение приемки, чтобы сразу "поймать" этот сигнал и создать задачу в своей системе.


Пример сценария обмена данными

Рассмотрим базовый сценарий - обмен данными по сделкам, когда есть внешняя учетная система, например, CRM, в которой работают менеджеры по продажам и хранится информация по квартирам, и стоит задача проводить в Базис Недвижимость (БН) передачу помещений, а также вести работу по устранению замечаний.

Главное, с чего начинается работа - передача базы объектов (квартир, паркингов и пр.) в Базис Недвижимость. Это необходимо, чтобы создать структуру данных и карту соответствий "ID объекта в БН" <-> "ID объекта во внешней системе". Это потребуется для всех дальнейших шагов по интеграции!

В шагах будет 2 варианта взаимодействия:

  • Ручной (по расписанию) на фидах - системы не связаны друг с другом, сами забирают данные из фида, это наиболее простой способ, но с ним сложно добиться именно двусторонней интеграции, когда изменения в одной системе передаются во вторую, и так в обе стороны. Проблемы могут возникнут при нарушении очередности загрузки, когда новые, еще не переданные, данные перезатираются пришедшим фидом. Для односторонней передачи подходит очень хорошо.
  • Автоматический (в реальном времени) на API и вебхуках - потребуется разработка промежуточного звена (шлюза) между БН и CRM, шлюз должен будет уметь авторизовываться в API обеих систем и выполнять запросы к ним.

Шаг 1. Передача актуальных данных по помещениям из CRM -> в БН

Самый простой и быстрый способ передать помещения в БН - сделать XML фид (файл с данными об объектах)

  1. В CRM создается экспорт всех помещений в фид в формате Базис.Недвижимость XML (описание формата https://iflat.io/blog/17-basis-xml-feed)
  2. В настройках БН указывается ссылка на этот фид (или загружается файл) и из него загружаются все дома и помещения (структура данных создается автоматически). В дальнейшем из этого же фида может проводиться повторная загрузка, чтобы актуализировать данные, например, если после обмеров БТИ поменялись площади - загружается еще раз.

На этом шаге мы загружем все объекты и обеспечиваем возможность обновлять данные в дальнейшем.

Шаг 2. Передача сделок и покупателей из CRM -> БН

Вариант 1. Редкая (по расписанию) передача данных:

Небходимо сформировать JSON-фид (по аналогии с квартирами) и вставить ссылку на фид на странице импорта в Базис Недвижимости - все данные по сделками и участникам будут загружены. Обновить данные можно повторной загрузкой. Пример фида: https://iflat.io/blog/22-basis-deal-json-feed

Вариант 2. Автоматизированная (в реальном времени) передача данных

На стороне CRM необходимо создать функцию, которая будет выполнять API-запросы к БН (документация по API здесь https://iflat.io/api/documentation):

  1. Авторизация в API (получение токена доступа)
  2. Выполнить POST-запрос на адрес ​/providers​/{providerId}​/deals. В запросе передается JSON-объект, в котором вся информация о сделке и ее участниках. Формат объекта равен формату JSON-фида из варианта №1. Если такой сделки еще нет в БН, она будет создана, если есть - данные в ней обновятся.

Шаг 3. Передача сделок и покупателей из БН -> CRM

Вариант 1. Редкая (по расписанию) передача данных:

В настройках Базис Недвижимость создается JSON-фид со всеми сделками и покупателями. Данные в фиде обновляются с заданным интервалом (можно указать от 1 часа до 1 суток). Со стороны внешней CRM системы разрабатывается функция, которая скачивает фид и разбирает данные на стороне CRM. Формат фида: https://iflat.io/blog/22-basis-deal-json-feed

Вариант 2. Автоматизированная (в реальном времени) передача данных

Данный вариант достигается путем использованием ряда методов API Базис Недвижимость и вебхуков:

  1. Создание сделки в БН (сделка может быть добавлена сотрудником, либо же создана клиентом - бронь на квартиру)
  2. При создании сделки в БН срабатывает Webhook на создание сделки - отправляется POST-запрос на указанный в настройках URL (по этому URL может быть шлюз/веб-сервис CRM системы). Данные, передаваемые внутри запроса - ресурс сущности, в данном случае это Deal (сделка). Все ресурсы и передаваемые в них данные, описаны в самом низу документации.
  3. Шлюз CRM системы авторизуется в API БН: метод ​/oauth​/token (получение токена доступа)
  4. Если кроме самой сделки, шлюзу нужны связанные данные, например данные клиентов по сделке, он может запросить дополнительные данные из БН, выполнив GET-запрос к API: ​​/deals​/{dealId}​/clients?embed=personal_data - в ответе вернется список всех клиентов из сделки, вместе с их паспортными данными.
  5. Шлюз CRM системы, получив данные сделки из БН, передает их в CRM систему - выполняет необходимые API вызовы к ней. Создается сделка в CRM.
  6. Шлюз выполняет POST-запрос к API БН: ​/externalObjects​/{provider}/maps и отправляет на него json-объект, содержащий "ID сделки из БН", и "ID созданной сделки в CRM системе" - этот запрос создает в БН карту соответствия ID этих сделок. Карта используется для дальнейшей идентификации сделки между двумя системами. 

Важно! Для чего нужен п.5 - в данной схеме информация по сделке отправляется вебхуком на шлюз CRM и не дожидается ответа от него, таким образом Базис Недвижимость "не знает", какой ID присвоился сделке в CRM системе и не может сохранить карту соответствия для нее. Однако, в дальнейшем может потребоваться обновить данные сделки внутри БН запросом из CRM системы, а если карты соответствий нет, БН не сможет понять, по какой из сделок пришли данные из CRM.


Схема обмена данными с участием сайта

Действия на схеме:

  • Покупатель отправляет заявку на бронирование квартиры через форму на сайте
  • Доступность квартиры проверяется в CRM системе
  • Если квартира доступна, создается сделка в Базис Недвижимости
  • Отправляется вебхук о создании сделки в CRM
  • В CRM создается сделка, после чего в БН отправляется ID созданной сделки (создается карта соответствия)
  • Покупатель получает зарегистрированный кабинет и видит в нем новую сделку (свою бронь)
  • Может работать с ней (например, прикладывать документы)
  • С какой-то периодичностью из CRM в БН отправляются данные по тем сделкам, которые были созданы сразу в CRM. Таким образом, информация в обеих системах синхронизируется, и у каждого покупателя появляется кабинет.




Часто задаваемые вопросы

Как пройти авторизацию в API для выполнения запросов

Чтобы иметь возможность выполнять запросы к API Базис Недвижимости, необходимо сначала получить авторизационный токен (access_token)

Выполняем запрос "POST /oauth/token", передаем логин/пароль и данные аккаунта, в ответ будет отправлен access (живет 1 сутки) и refresh (живет 30 дней) токены.

Дальше во все запросы добавляем заголовок  'Authorization: Bearer ВашAccessТокен'

Все авторизационные методы описаны в документации к API, раздел Авторизация.

Увидеть данные для подключения к своему аккаунту можно в разделе Настройки -> Своя интеграция.

Как с помощью API собрать сделку по отдельности (создать сделку, прикрепить участников)

  1. Создаем покупателя методом "POST /users", передаем его ФИО и номер телефона. В ответ получаем ресурс User, в котором есть ID созданного пользователя в базе данных.
  2. Если нужно сохранить паспортные данные, то выполняем еще дополнительно метод "PUT /users/{userId}/personalData", куда передаем все данные покупателя.
  3. Создаем сделку методом "POST /deals", передаем ID помещения из БН (room_id) и номер/дату договора (при необходимости). В ответ получаем ресурс Deal, в котором есть ID созданной сделки в базе данных. Важно! Передавать надо внутренний room_id из Базис Недвижимость, чтобы узнать все room_id и их соответствие вашим ID из CRM, можно выполнить команду /externalObjects/Room, которая вернет список всех загруженных квартир и их внутренние room_id вместе с вашими external_id. Предполагается, что эта карта соответствий после первого получения будет храниться и на стороне CRM, чтобы каждый раз не нужно было получать заранее /externalObjects/Room (сократить запросы, ускорить процесс).
  4. Когда у нас есть ID покупателя и ID сделки, выполняем "POST /deals/{dealId}/clients", передаем туда ID покупателя, таким образом прикрепляем покупателя к сделке.

Как получать дату приемки помещения в CRM

Два варианта:

  • Получение списка всех приемок по расписанию с помощью API, например, за день: "GET /inspections?dateFrom=10.06.2020&dateTo=10.06.2020" и сохранение данных по ним в CRM системе.
  • Указать в Настройки -> Webhooks свой URL, на который будут отправляться данные о появлении новой приемки и сразу сохранять дату в CRM. Для этого на стороне CRM нужно создать обработчик, который будет принимать данные из БН. В меню "Настройки -> Webhooks" добавляем вебхук с типом "Создание приемки" и указываем ссылку на обработчик CRM.

Также есть вебхук на изменение приемки, можно использовать для получения статуса приемки в реальном времени.

Как получать новые технические заявки в CRM

  • Пполучение списка всех техзаявок по расписанию с помощью API, например, за день: "GET /claims?dateFrom=10.06.2020&dateTo=10.06.2020" и сохранение данных по ним в CRM системе.
  • Указать в Настройки -> Webhooks свой URL, на который будут отправляться данные о появлении новой технической заявки и сразу сохранять информацию в CRM. Для этого на стороне CRM нужно создать обработчик, который будет принимать данные из БН. В меню "Настройки -> Webhooks" добавляем вебхук с типом "Создание техзаявки" и указываем ссылку на обработчик CRM.

Как получать свободные временные промежутки для записи на приемку

Чтобы получить все дни, в которые возможна запись на приемку нужно выполнить запрос (для этого метода нужно знать ID дома):

"GET /houses/{houseId}/inspectionsPeriods?groupBy=date" 

Чтобы получить все временные отрезки за выбранный день и информацию по ним (занято/свободно), выполяем метод:

"GET /houses/{houseId}/inspectionsDays/{date}/times", где date - это дата в формате 10.06.2021


Похожие статьи
Кастомизация виджета личного кабинета Смотреть полностью
Установка кабинета покупателя на свой сайт Смотреть полностью
Связь виджета с внешними скриптами Смотреть полностью
Отправка Webhooks по событиям Смотреть полностью