Интеграция и обмен данными с внешней CRM системой
Оглавление
1. Способы загрузки и обновления данных в Базис Недвижимость
1.2. Загрузка сделок и клиентов
2. Способы получения данных из Базис Недвижимость
3. Сценарий обмена данными (ПРИМЕР)
4. Схема обмена данными с участием сайта
Для чего нужна интеграция
Если у вас есть внешняя система и часть отделов продолжают работать в ней, а часть переходят на работу в системе Базис Недвижимость (БН), может возникнуть потребность в синхронизации данных между системами, в базовом сценарии это три основных пункта:
- Данные по помещениям (площади, цена)
- Данные по сделкам (статус, сумма, выбранное помещение)
- Данные по участникам сделок (ФИО, телефон, паспортные данные)
Способы загрузки и обновления данных в Базис Недвижимость
Данные по помещениям
Есть три варианта по загрузке помещений (рекомендуем вариант 2):
1) Импорт из Excel (малая степень автоматизации, требует минимальное кол-во ресурсов от вашего отдела разработки) - вы можете создать в своей системе выгрузку помещений в файл Excel в требуемом формате, а затем загрузить этот файл в кабинете Базис Недвижимость.
Плюсы:
+ Легко начать работать
+ Минимум разработки на вашей стороне
Минусы:
- Файл нужно формировать каждый раз заново и вручную загружать в БН
- Есть риск неверно сопоставить колонки при загрузке и "испортить данные" (придется загружать еще раз, чтобы исправить)
2) Импорт из фида Рекомендуем! (высокая степень автоматизации, средняя сложность разработки) - Создайте в своей системе автоматический Фид (ссылка на xml-файл, который формируется динамически из вашей базы данных) и укажите ссылку на него в кабинете БН, помещения будут загружены, а при повторной загрузке того же фида, данные будут обновляться, таким образом можно держать данные актуальными в обеих системах.
Описание фида для загрузки в Базис Недвижимость здесь: https://iflat.io/blog/17-basis-xml-feed
Плюсы:
+ Данные приходят всегда в одном формате, что исключает человеческий фактор и появление ошибок
+ Минимум расхождений в данных. Один и тот же фид можно загружать каждый день, в нем всегда актуальные данные, а значит каждый день актуальные данные будут попадать и в Базис Недвижимость
+ Если у вас уже есть выгрузка квартир на Яндекс.Недвижимость, достаточно будет добавить к ней несколько полей, чтобы этот фид подошел и для Базис Недвижимость
Минусы:
- Потребуются ресурсы на вашей стороне для разработки такого фида
3) Создание и обновление объектов через методы API (самая высокая степень автоматизации, высокая сложность разработки) - используя наше Rest API, вы можете полностью создавать и контролировать всю структуру данных в Базис Недвижимость, добавлять дома/этажи/помещения, менять их свойства, удалять, любые действия.
Описание документации по API здесь: https://iflat.io/api/documentation
Плюсы:
+ Полный контроль над данными
Минусы:
- Потребуются большие ресурсы на вашей стороне для разработки подобной интеграции (вникнуть в структуру данных, написать функции по работе с каждым объектом)
Данные по сделкам и покупателям
Как и в случае с помещениями, есть три варианта, с теми же плюсами и минусами:
- Импорт из Excel (низкая автоматизация, минимум затрат ресурсов)
- Импорт из Фида (высокая автоматизация, среднее количество ресурсов) - описание формата фида https://iflat.io/blog/22-basis-deal-json-feed
- Прямая работа через 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 фид (файл с данными об объектах)
- В CRM создается экспорт всех помещений в фид в формате Базис.Недвижимость XML (описание формата https://iflat.io/blog/17-basis-xml-feed)
- В настройках БН указывается ссылка на этот фид (или загружается файл) и из него загружаются все дома и помещения (структура данных создается автоматически). В дальнейшем из этого же фида может проводиться повторная загрузка, чтобы актуализировать данные, например, если после обмеров БТИ поменялись площади - загружается еще раз.
На этом шаге мы загружем все объекты и обеспечиваем возможность обновлять данные в дальнейшем.
Шаг 2. Передача сделок и покупателей из CRM -> БН
Вариант 1. Редкая (по расписанию) передача данных:
Небходимо сформировать JSON-фид (по аналогии с квартирами) и вставить ссылку на фид на странице импорта в Базис Недвижимости - все данные по сделками и участникам будут загружены. Обновить данные можно повторной загрузкой. Пример фида: https://iflat.io/blog/22-basis-deal-json-feed
Вариант 2. Автоматизированная (в реальном времени) передача данных
На стороне CRM необходимо создать функцию, которая будет выполнять API-запросы к БН (документация по API здесь https://iflat.io/api/documentation):
- Авторизация в API (получение токена доступа)
- Выполнить 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 Базис Недвижимость и вебхуков:
- Создание сделки в БН (сделка может быть добавлена сотрудником, либо же создана клиентом - бронь на квартиру)
- При создании сделки в БН срабатывает Webhook на создание сделки - отправляется POST-запрос на указанный в настройках URL (по этому URL может быть шлюз/веб-сервис CRM системы). Данные, передаваемые внутри запроса - ресурс сущности, в данном случае это Deal (сделка). Все ресурсы и передаваемые в них данные, описаны в самом низу документации.
- Шлюз CRM системы авторизуется в API БН: метод /oauth/token (получение токена доступа)
- Если кроме самой сделки, шлюзу нужны связанные данные, например данные клиентов по сделке, он может запросить дополнительные данные из БН, выполнив GET-запрос к API: /deals/{dealId}/clients?embed=personal_data - в ответе вернется список всех клиентов из сделки, вместе с их паспортными данными.
- Шлюз CRM системы, получив данные сделки из БН, передает их в CRM систему - выполняет необходимые API вызовы к ней. Создается сделка в CRM.
- Шлюз выполняет 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 собрать сделку по отдельности (создать сделку, прикрепить участников)
- Создаем покупателя методом "POST /users", передаем его ФИО и номер телефона. В ответ получаем ресурс User, в котором есть ID созданного пользователя в базе данных.
- Если нужно сохранить паспортные данные, то выполняем еще дополнительно метод "PUT /users/{userId}/personalData", куда передаем все данные покупателя.
- Создаем сделку методом "POST /deals", передаем ID помещения из БН (room_id) и номер/дату договора (при необходимости). В ответ получаем ресурс Deal, в котором есть ID созданной сделки в базе данных. Важно! Передавать надо внутренний room_id из Базис Недвижимость, чтобы узнать все room_id и их соответствие вашим ID из CRM, можно выполнить команду /externalObjects/Room, которая вернет список всех загруженных квартир и их внутренние room_id вместе с вашими external_id. Предполагается, что эта карта соответствий после первого получения будет храниться и на стороне CRM, чтобы каждый раз не нужно было получать заранее /externalObjects/Room (сократить запросы, ускорить процесс).
- Когда у нас есть 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