Интеграция с внешними системами

Интеграция платформы Домиленд с внешними системами — это процесс объединения двух или более программных решений для обмена данными и автоматизации работы. Она позволяет синхронизировать информацию между различными системами, что повышает эффективность бизнес-процессов. Например, упрощает управление недвижимостью, улучшает качество предоставляемых услуг и контроль за финансовыми операциями.

Интеграция с платформой Домиленд осуществляется с помощью импорта и экспорта данных. Существует два основных способа настроить обмен данными:

• Интеграция по API. API — это набор средств, которые позволяют программам взаимодействовать друг с другом. Интеграция по API позволяет обмениваться данными между CRM и внешними системами в режиме реального времени.
• Интеграция через XML. XML — это язык разметки, который используется для обмена данными между различными системами. Интеграция через XML позволяет передавать данные в виде структурированных файлов или фидов. Этот способ может быть полезен для интеграции с системами, которые не поддерживают API.

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

• Импорт позволяет загрузить большой объем данных за короткое время, тогда как ручной ввод такого же объема может потребовать много ресурсов.
• Ручной ввод данных подвержен человеческим ошибкам. Импорт минимизирует эти риски, так как данные переносятся автоматически из проверенного источника.
• Импорт данных можно автоматизировать, настроив расписание.
• Экспорт данных позволяет передавать информацию в другие системы, например, в 1С.

Платформа Домиленд позволяет девелоперам и управляющим организациям получать широкий набор данных из внешних систем или наоборот, экспортировать данные. Например, платежи, клиентов, объекты, показания счетчиков, новости и многое другое.

Ниже представлен список данных, которые можно экспортировать и импортировать через API и XML.
По ссылкам можно перейти к инструкциям, где подробно описываются методы, атрибуты, а также представлены примеры запросов, ответов и файлов импорта/экспорта.

Есть дополнительные пояснения об импорте клиентов УО по API, которые рассматривают сценарии при совпадении данных и решение таких ситуаций.

FTP-сервер позволяет организовать обмен данными между Домиленд и другими системами с помощью XML-файлов. Сервер выступает в роли промежуточного звена, через которое Домиленд отправляет и получает информацию.

Для обмена данными партнеры могут воспользоваться как бесплатным сервером Домиленд, так и своим собственным сервером. В первом случае доступ к серверу настроят сотрудники Домиленд.

Если организация использует собственный сервер, ее сотрудники могут самостоятельно настроить доступ. Для этого перейдите в раздел «Администрирование» → «Интеграция» → вкладка «Обмен данными» → «Настройки FTP» и укажите параметры доступа:

• Адрес и порт сервера для подключения
• Использовать SSL, если требуется зашифровать соединение для защиты передаваемой информации. На стороне FTP-сервера должен быть установлен SSL-сертификат.
• Имя пользователя и пароль
• Корневая директория на сервере, используемая для импорта данных в систему и экспорта из нее.
• Принудительно использовать кодировку utf-8 при подключении к серверу. Это поможет избежать проблем при чтении файлов с названиями на кириллице.

Чтобы убедиться, что данные введены верно, нажмите на кнопку «Тест соединения». В случае успешного соединения будет показано всплывающее уведомление с текстом «ОК».

Сотрудники УО могут настроить автоматический импорт данных в CRM-систему, чтобы не приходилось вручную заносить в CRM большие объемы информации.

Данные для Эксплуатации можно импортировать с использованием XML-файлов и FTP-сервера. Новости и данные для продуктов Витрины можно передавать через XML-фиды. Ниже описана настройка автоматического импорта для каждого из этих способов.

XML-файлы
Прежде всего требуется настроить FTP-соединение с сервером, это можно сделать в разделе «Администрирование» → «Интеграция» → вкладка «Обмен данными» → «Настройки FTP».

FTP-сервер служит для безопасной передачи файлов между системами. В данном случае, внешняя система должна отправлять на FTP-сервер файлы с данными в формате XML. Домиленд, в свою очередь, будет периодически проверять этот сервер и забирать необходимые файлы для дальнейшей обработки.

Если FTP-соединение успешно настроено, на вкладке «Обмен данными» нужно выбрать «Импорт» и в одном из блоков (например, «Импорт начислений») заполнить следующие параметры:

• Выбор метода — XML. Требования к структуре и примеры XML-файлов для разных данных описаны здесь.
• Уведомлять на email — возможность получать на электронную почту отчеты об успешном или неудачном импорте. В отчете могут быть указаны ошибки и предупреждения, например: лицевой счет не найден, или организация не найдена. Если ошибок нет, приходит просто статус ОК.
• Адрес файла (ов) — путь к файлам, откуда нужно брать данные для интеграции (ссылка или путь на FTP-сервере). Если файл находится не в корневом каталоге сервера, путь к нему указывается через слэши «/», как у адресов веб-страниц. В поле можно указать адреса нескольких файлов через запятую, например: /objects/z84/invoices.xml, /objects/p32/invoices.xml, /objects/s15/invoices.xml.
• Удалять файлы выгрузки после прочтения. Опция позволит избежать ситуации, когда на FTP-сервере заканчивается свободное место.
• Расписание — частота импорта данных. Указывается время и / или дни, в которые нужно проводить операцию. Расписание не учитывает поля, в которых написана звездочка. Если указаны только минуты, операция будет запускаться раз в час, например: 19 минут и звездочки в остальных полях = запуск в 10:19, 11:19 и так далее. Если указаны минуты и часы, операция будет запускаться раз в день, например: 19 минут, 22 часа и звездочки в остальных полях = запуск каждый день в 22:19. Другие поля работают по аналогии: запуск в конкретное число месяца, запуск в конкретный месяц, запуск в конкретный день недели. Можно ввести несколько чисел через запятую.

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

Для первичного теста или когда нужен ручной запуск, можно использовать кнопку «Запустить сейчас» — тогда через письмо на почту сотрудник сразу узнает, все ли в порядке с файлом данных и настройками интеграции.

Если в ходе импорта произошла хотя бы одна ошибка, операция останавливается, при этом уже импортированные данные остаются в CRM.

XML-фиды
Если данные импортируются в CRM через XML-фид, в поле «Выбор метода» выберите «Url». Укажите прямую ссылку на фид в поле «Url адрес файла». Для хранения фидов можно использовать облачное хранилище или собственный сервер. Например, корректная ссылка на файл в облачном хранилище Dropbox должна содержать параметр «dl=1» в конце: www.dropbox.com/s/idfile123/filename.xml?dl=1.
Поля «Расписание» и «Уведомлять на email» заполняются по аналогии с инструкцией выше.

Кроме почты есть еще один способ посмотреть результат операции, и не только импорта: выбрать «Лог» на вкладке «Обмен данными».

Сотрудники УО могут настроить автоматический экспорт данных во внешнюю систему (например, платежей или показаний ИПУ), чтобы не приходилось вручную переносить большие объемы информации из CRM.

Прежде всего для этого требуется настроить FTP-соединение с сервером, это можно сделать в разделе «Администрирование» → «Интеграция» → вкладка «Обмен данными» → «Настройки FTP».

FTP-сервер служит для безопасной передачи файлов между системами. В данном случае, Домиленд будет автоматически отправлять на FTP-сервер файлы с экспортируемыми данными в формате XML. Внешняя система, в свою очередь, должна периодически проверять этот сервер и забирать необходимые файлы.

Если FTP-соединение успешно настроено, на вкладке «Обмен данными» нужно выбрать «Экспорт» и в одном из блоков (например, «Экспорт показаний ИПУ») заполнить следующие параметры:

• Выбор метода — на данный момент, интеграция доступна только с помощью XML-файлов. Требования к структуре и пример XML-файла такие же, как для импорта.
• Уведомлять на email — возможность получать на электронную почту отчеты об успешном или неудачном экспорте. В отчете могут быть указаны ошибки и предупреждения, например: лицевой счет не найден, или организация не найдена. Если ошибок нет, приходит просто статус ОК.
• Каталог экспорта — путь к месту, куда нужно выгрузить данные. Если поле оставить пустым, то файл будет экспортирован в корневую директорию FTP-сервера, указанную на вкладке «Обмен данными» → «Настройки FTP».
• Шаблон имени файла — вместо простого ввода имени указывается шаблон, из которого составляется имя файла. Это нужно для того, чтобы каждый экспортируемый файл был с уникальным названием. Шаблон позволяет включить текущую дату в имя файла. Формат шаблона и пример указаны отдельно для каждого вида данных.
• Расписание — частота экспорта данных. Указывается время и / или дни, в которые нужно проводить операцию. Расписание не учитывает поля, в которых написана звездочка. Если указаны только минуты, операция будет запускаться раз в час, например: 19 минут и звездочки в остальных полях = запуск в 10:19, 11:19 и так далее. Если указаны минуты и часы, операция будет запускаться раз в день, например: 19 минут, 22 часа и звездочки в остальных полях = запуск каждый день в 22:19. Другие поля работают по аналогии: запуск в конкретное число месяца, запуск в конкретный месяц, запуск в конкретный день недели. Можно ввести несколько чисел через запятую.

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

Для первичного теста или когда нужен ручной запуск, можно использовать кнопку «Запустить сейчас» — тогда через письмо на почту сотрудник сразу узнает, все ли в порядке с файлом данных и настройками интеграции.

Как уже упоминалось выше, результат операций можно посмотреть не только через электронную почту, но и открыв «Лог».

В разделе «Администрирование» → «Интеграция» → вкладка «Обмен данными» → «Лог» хранится история операций, которые связанны с интеграцией:

• Импорт данных по API и файлов через CRM
• Импорт XML-файлов и фидов по расписанию
• Экспорт XML-файлов по расписанию

Просматривать лог можно в CRM или получать его через API.

Каждая запись в таблице содержит следующую информацию:
(1) Статус — показатель текущего состояния операции импорта или экспорта. Различные статусы информируют пользователя о том, на какой стадии находится обработка данных и каков ее результат:

• Выполняется — операция запущена и находится в процессе обработки.
• Выполнено — операция прошла успешно, без ошибок и предупреждений.
• Ошибка — произошел сбой операции, некоторые данные могли быть обработаны до возникновения ошибки.
• Предупреждение — операция выполнена частично. Все данные, кроме тех, что указаны в столбце «Сообщения», были обработаны.
• Дубликат — импорт по API был прерван из-за обнаружения дубликата. Это значит, что идентичный запрос на импорт по API уже выполнялся в течение последних трех дней. Такая проверка помогает предотвратить обновление одних и тех же данных в CRM.

(2) Задача — название операции и ее номер (например, «Экспорт платежей 4180684»).
(3) Метод — способ, который использовался для обмена данными:

• XML — операции с XML-файлами.
• URL — операции по API, импорт фидов по ссылке и импорт файлов через CRM (например, Excel-файлы с начислениями).

(4) Сообщение — информация об успешной операции или описание ошибки/предупреждения.
(5) Создано — дата запуска операции.
(6) Обновлено — дата окончания обработки операции.

В разделе доступен текстовый поиск по данным в столбце «Сообщение». Список операций можно отфильтровать с помощью кнопки «Фильтры»: по дате создания, статусу, типу задачи, методу.

Согласно 209-ФЗ от 21.07.2014, управляющие организации обязаны передавать информацию о своей деятельности в ГИС ЖКХ. Платформа Домиленд позволяет настроить обмен данными с ГИС ЖКХ. Подключение этого функционала доступно с помощью поддержки.

Основная целевая аудитория для интеграции Домиленд с ГИС — новые партнеры, у которых нет других интеграций с Домиленд. Например, если уже работает синхронизация данных с модулем 1C, не получится использовать интеграцию с ГИС ЖКХ.
Цели функционала:
1) Ускорить внедрение новых управляющих организаций, которые еще не имеют интеграций с Домиленд.
2) Предоставлять жителям в мобильном приложении актуальную информацию по Счетам ЖКУ/КР, показаниям счетчиков.

После того как интеграция настроена, сотрудники могут продолжать работу в своей системе и ГИС ЖКХ, а житель увидит актуальные данные в приложении Домиленд. Синхронизация данных происходит ежедневно.
Обработка ошибок при интеграции с ГИС ЖКХ происходит на стороне Домиленд. Это отличает процесс от обмена данными по XML или API, когда могут потребоваться исправления на стороне партнера.

Синхронизация данных происходит по юрлицам, которые обслуживают дома. Система позволяет:

• Импортировать из ГИС ЖКХ данные о помещениях, лицевых счетах, клиентах, счетчиках. Если включен этот импорт, доступен остальной обмен данными.
• Импортировать из ГИС ЖКХ показания счетчиков
• Экспортировать в ГИС ЖКХ показания счетчиков, которые внес житель. Предполагается, что в ГИС ЖКХ и так передаются те показания, которые вносят сами сотрудники через систему управляющей организации, поскольку это требуется по закону.
• Импортировать из ГИС ЖКХ счета за ЖКУ и данные по оплате этих счетов

Важно! При интеграции с ГИС ЖКХ не создаются новые объекты. Поэтому для синхронизации данных необходимо, чтобы в CRM были объекты с заполненными ФИАС идентификаторами. ФИАС дома обязателен для всей синхронизации с ГИС ЖКХ, объекты без него игнорируются. Остальные ФИАС идентификаторы нужны, чтобы из объекта импортировать адрес в данные помещения.

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

Чтобы настроить отправку уведомлений, перейдите в раздел «Администрирование» → «Интеграция» → вкладка «Онлайн уведомления» → «Настройки» и выполните следующие действия.
(1) Выберите режим отправки уведомлений:

• Общий адрес — все уведомления будут отправляться на один указанный адрес.
• Отдельные адреса — для каждого типа уведомлений можно указать свой уникальный адрес. Такой режим обеспечит более гибкую настройку и контроль над уведомлениями.

(2) В зависимости от выбранного режима, укажите общий адрес или задайте отдельные адреса для каждого типа уведомлений. Уведомления будут отправляться только по тем событиям, для которых указан адрес.
Адреса должны поддерживать протокол HTTPS. Чтобы обеспечить дополнительную защиту, можно использовать базовую HTTP-авторизацию. В таком случае адрес должен быть указан в формате: https://user:password@example.com/index.

Когда внешняя система получает уведомление, она должна вернуть HTTP-код 200. Иначе уведомление считается не доставленным и будет отправляться повторно в течение суток, с периодичностью не чаще одного раза в час. Через сутки попытки доставить уведомление прекращаются.

Все уведомления подписываются уникальным ключом. Это гарантирует их подлинность и позволяет убедиться в том, что их действительно отправляет Домиленд. Подробнее об этом в Public API.

Для каждого типа уведомлений предусмотрен определенный набор данных. По ссылкам можно перейти к инструкциям, где подробно описывается структура запроса в зависимости от типа уведомления, а также представлены примеры таких запросов:

• Эксплуатация
• Строительство

Информация об отправленных уведомлениях с помощью вебхуков хранится в разделе «Администрирование» → «Интеграция» → вкладка «Онлайн уведомления» → «Лог событий».

Каждая запись в таблице содержит следующую информацию:

• Код ответа — указывает на результат выполнения запроса. 200 — успех, другие коды — ошибка.
• Адрес вызова — URL, на который было отправлено уведомление.
• Тело запроса — отправленная информация о произошедшем событии в формате JSON.
• Тело ответа — информация о том, как был обработан запрос на стороне внешней системы.
• Дата создания — когда была попытка отправки уведомления.

Платформа Домиленд предоставляет широкие возможности для интеграции с информационной системой (ИС) девелопера. Взаимодействие между системами происходит через API. В отличие от простого импорта и экспорта, интеграция с ИС Девелопера обеспечивает более гибкое управление данными. Возможна автоматизация различных процессов при работе с недвижимостью — как для клиентов, так и на стороне сотрудников.

Когда клиент совершает действие в приложении (например, открывает список своих записей на приемку), Домиленд отправляет запрос в адрес ИС Девелопера. После этого ИС Девелопера обрабатывает запрос и возвращает необходимые данные обратно.

Чтобы настроить интеграцию, сначала необходимо реализовать соответствующие методы на стороне системы девелопера.

Ниже представлен список возможных сценариев взаимодействия и методы, которые вызываются на стороне Домиленд. По ссылкам можно перейти к подробному описанию, а также посмотреть примеры запросов и ответов.

После того как необходимые API-методы реализованы на стороне девелопера, нужно выполнить настройки на платформе Домиленд. Для этого перейдите в раздел «Администрирование» → «Интеграция» → вкладка «Система девелопера» → «Настройки» и укажите параметры доступа:

(1) Адрес. URL-адрес системы девелопера, на который будут отправляться запросы со стороны Домиленд.
Все запросы к системе девелопера подписываются уникальным ключом, он также отображается на вкладке с параметрами интеграции. Такая подпись гарантирует подлинность запросов и позволяет убедиться, что их действительно отправляет Домиленд. Подробнее об этом в Public API.

(2) Проверка паспортных данных. Когда опция отключена, запись на приемку проходит без шага проверки паспортных данных. В ином случае, первым шагом при записи на приемку будет проверка паспортных данных. Клиент сможет просмотреть свои данные и внести изменения, если потребуется. В случае изменения данных они будут отправлены в систему девелопера через API. Функционал работает только совместно с опцией «Доверенные лица».

(3) Онлайн-бронирование. Активирует функционал онлайн-бронирования, при этом становятся доступны следующие настройки:

• Возможность ставить помещение в резерв при начале бронирования — если опция отключена, лот снимется с продажи только после того, как клиент оплатит или завершит бронирование, если оно бесплатное.
• Возможность отмены бронирования — клиенты смогут отменять незавершенные бронирования через приложение. Незавершенным считается бронирование, при котором клиент прервал заполнение данных на одном из шагов. В карточке такого бронирования будет кнопка отмены. В момент отмены Домиленд вызывает соответствующий метод.
• Синхронизация статуса каждого бронирования с ИС Девелопера при каждом запросе пользователя — если включено, то при открытии клиентом экрана со списком бронирований или карточки бронирования, Домиленд вызывает метод получения информации о бронировании. В ответ система девелопера возвращает актуальную информацию. Если синхронизация отключена, то статус бронирования в Домиленд не будет обновляться, даже если он изменится в системе девелопера.
• Автоматическое заполнение формы бронирования данными клиента — если опция включена, то при бронировании недвижимости Домиленд отправит запрос в ИС Девелопера на получение данных клиента. Если данные будут получены, они автоматически подставятся в соответствующие поля формы бронирования.

(4) Сделки. Включает функционал продукта «Сделка», чтобы клиент мог видеть информацию о приобретенной недвижимости. Девелопер передает всю информацию через API в ответ на запрос от Домиленд. Полученные данные отображаются на витрине в мобильном приложении.

(5) Обратная связь. Включает функционал обращений. Клиенты через мобильное приложение смогут задавать вопросы сотрудникам девелопера. В отличие от чатов с оперативным общением, обращения помогают нагляднее отслеживать статус решения своих запросов.

• Возможность отмены обращения — клиенты смогут отозвать свое обращение, если оно находится в статусе «Получено».
• Номер телефона для обратной связи — номер, по которому клиенты смогут связаться с девелопером из списка обращений.
• Количество дней, в течение которых дается ответ по обратной связи — если клиент еще не обращался к девелоперу, то в списке обращений отображается текст: «Ответ по вашему обращению будет предоставлен в течение N дней». Вместо N будет указано количество дней, заданное в настройках опции. Если клиент уже обращался к девелоперу, то вместо этого сообщения он увидит список своих обращений.

(6) Рассрочка. Включает возможность для клиентов создавать заявки на изменение даты и суммы платежа по рассрочке, а также проверять статус таких заявок. Такие заявки девелопер обрабатывает на своей стороне.

(7) Приемка

• Без синхронизации — режим, при котором работают функции запись на приемку и график приемок, но не работают аналитика, недочеты, формы приемок. Реализовано для ситуации, когда у девелопера уже есть свой механизм приемок, и часть функций от Домиленд считаются излишними.
• С синхронизацией — режим, при котором работает весь доступный функционал: запись на приемку, график приемок, формы приемок, аналитика, недочеты.
• Отключено — отключает интеграцию с системой девелопера по приемке.

(8) Доверенные лица. Когда опция включена, клиент может проводить приемку не лично, а записать своего представителя на осмотр помещения. Подробнее об этом в Public Api. Функционал работает только совместно с опцией «Проверка паспортных данных».

Информация об операциях по обмену данными между платформой и ИС девелопера хранится в разделе «Администрирование» → «Интеграция» → вкладка «Система девелопера» → «Лог вызовов».

Просматривать лог можно в CRM или получать его через API.

Каждая запись в таблице содержит следующую информацию:

• Код ответа — указывает на результат выполнения запроса. 200 — успех, другие коды — ошибка.
• Адрес вызова — URL, на который был отправлен запрос со стороны Домиленд. Он включает в себя основную часть, указанную в настройках, и конечную точку назначения запроса.
• Тело запроса — информация в формате JSON, отправленная в систему девелопера с помощью методов POST, PUT и PATCH. В методах GET и DELETE отсутствует тело запроса.
• Тело ответа — информация о том, как был обработан запрос на стороне системы девелопера.
• Создано — дата отправки запроса в систему девелопера.