API Передача ключей

Для получения возможности использовать функционал API по передаче ключей предварительно необходимо настроить интеграцию Вашего сайта с MACRO.

Бизнес-процесс по передаче квартир

Происходит в 3 этапа:

1. Ваш сервис запрашивает список объектов, которые готовы к передаче. API в ответ возвращает список из номеров объектов, сгруппированный по домам. В выборку попадают объекты в статусе Сделка проведена с указанной фактической датой готовности к передаче.

2. Пользователь выбирает интересующий его дом и удобную дату. Сервис отправляет эти данные в API и в ответ получает список свободных временных промежутков для записи на передачу.

3. Сервис отправляет в API запрос на бронирование времени под передачу.

Получение списка объектов готовых к передаче

Параметры запроса

https://api.macrocrm.ru/estate/transfer/getReadyFlats/

Метод: GET или POST

Параметр	Обяз.	Пример	Описание
time	Да	1234567890	Unix timestamp запроса
domain	Да	"вашсайт.рф"	Домен, зарегистрированный в системе MACRO
token	Да	md5(domain+time+app_secret)	Пример на PHP: $token = md5($domain . time() . $app_secret)
category	Да	storageroom	Ограничивает выборку объектов с учётом указанной категории недвижимости: — квартиры: flat — машино-места: garage — кладовые: storageroom — коммерческие помещения: comm

Пример запроса

{
"domain": "вашсайт.рф",
"time": "1623717393",
"token": "4ad523e0f803420bc52062a3b76658d0"
}

Пример ответа

{
    "status_code": 200,
    "data": {
        "houses": [
            {
                "id": "123",
                "title": "3 очередь бизнес-класс",
                "flats": [
                    "1.8-12-1",
                    "1.8-13-2",  …
                ]
            },
            {
                "id": "124",
                "title": "Бизнес-класс 2 очередь",
                "flats": [
                    "К-1.4-7-1"
                ]
            },  ….             
        ]
    },
    "message": "Выполнено"
}

Параметр	Описание
status_code	Код ответа сервера
message	В случае ошибки содержит её описание
data.houses	Массив со списком домов
data.houses[].id	ID дома в системе MACRO
data.houses[].title	Название дома в системе MACRO
data.houses[].flats	Массив с номерами квартир, готовых к передаче

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

Параметры запроса

https://api.macrocrm.ru/estate/transfer/getFreeTimes/

Метод: GET

Параметр	Обяз.	Пример	Описание
time	Да	1234567890	Unix timestamp запроса
domain	Да	"вашсайт.рф"	Домен, зарегистрированный в системе MACRO
token	Да	md5(domain+time+app_secret)	Пример на PHP: $token = md5($domain . time() . $app_secret)
transfer_date	Да	"2020-06-11T00:00:00+05:00"	Дата, для которой нужно вернуть список доступных временных промежутков для записи на передачу квартир. Должна быть в формате ISO 8601 (DATE_ATOM).
house_id	Да	123	ID дома в системе MACRO, по которому нужно вернуть список. Параметр обязательный, если Вы для каждого дома используете отдельный график передачи квартир

Пример тела запроса

{
    "domain": "вашсайт.рф",
    "time": "1623095129",
    "token": "0e8e424732fccbe827ca486feb925c47",
    "transfer_date": "2020-06-11T00:00:00+05:00",
    "house_id": "123"
}

Пример ответа от сервера

{
    "status_code": 200,
    "data": {
        "08:30",
        "09:00",
        "13:00",
        "17": "13:30",
    },
    "message": "Выполнено"
}

Параметр	Описание
status_code	Код ответа сервера
message	В случае ошибки содержит её описание
data	Массив со списком доступных временных промежутков

Резервирование времени для осмотра и передачи ключей

Важно! Убедитесь что в настройке компании «Передача ключей: Сотрудники компании, ответственные за передачу квартир» указан хотя бы один ответственный менеджер.

Параметры запроса

https://api.macrocrm.ru/estate/transfer/add/

Метод: POST

Заголовок: Content-Type: application/json

Формат данных: JSON

Параметр	Тип	Обяз.	Пример	Описание
domain	string	Да	"вашсайт.рф"	Домен, зарегистрированный в системе MACRO
transfer_date	string	Да	"2025-08-27T10:00:00+03:00"	Планируемая дата и время осмотра. Должна быть в формате ISO 8601 (DATE_ATOM).
phone	string	Да	"[phone]"	Контактный номер телефона покупателя. Номер будет приведен к формату +7.XXXXXXXXXX для поиска в системе MACRO.
name	string	Да	"Иванов Иван Иванович"	Полное имя покупателя. Используется для более точного поиска контакта в системе MACRO.
flat_num	string/integer	Да	"1.9-7-4"	Номер объекта недвижимости (квартиры, машино-места, кладовой и т.д.)
house_id	integer	Да	8561992	ID дома в системе MACRO, в котором находится объект недвижимости
category	string	Да	"flat"	Категория объекта недвижимости, в который требуется добавить запись на осмотр: — квартиры: flat — машино-места: garage — кладовые: storageroom — коммерческие помещения: comm Если категория не будет передана, то запись на осмотр добавится в первый найденный объект с совпадающим номером.
manager_id	integer	Нет	"86998"	ID менеджера в системе MACRO, которого Вы хотите назначить ответственным за передачу ключей в объекте недвижимости. Должен быть указан в настройке компании «Передача ключей: Сотрудники компании, ответственные за передачу квартир».
token	integer	Да	"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ"	Пример на PHP: $token = md5($domain . time() . $app_secret)
time	intege	Да	1704076800	Unix timestamp запроса

Пример запроса

{
    "domain": "вашсайт.рф",
    "transfer_date": "2025-08-27T10:00:00+03:00",
    "phone": "[phone]",
    "name": "Иванов Иван  Иванович",
    "flat_num": "1.9-7-4",
    "house_id": 8561992,
    "category": "flat",
    "manager_id": 86998,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ",
    "time": 1704076800,
}

Пример успешного ответа от сервера

{
    "status_code": 200,
    "data": {
        "message": "Дата осмотра зарезервирована"
    },
    "message": "Спасибо! Мы записали Вас на указанное время",
    "success": true
}

Пример ответа от сервера с ошибкой

{
    "status_code": 609,
    "error": true,
    "message": "Выбранная дата недоступна для записи"
}

Параметр	Описание
status_code	Код ответа сервера
error	Указание на наличие ошибки
success	Указание на успешное выполнение запроса
message	Описание ошибки или сообщение об успешном выполнении запроса

Описание возможных ошибок

Код	Сообщение	Причина
-	Метод не поддерживается	Использован метод, отличный от POST
603	Укажите номер телефона	Поле phone отсутствует или имеет неверный формат
604	Для резервирования времени нужно указать номер квартиры	В запросе отсутствуют и поле name, и поле flat_num
604	Для резервирования времени нужно указать дом	Поле house_id отсутствует или равно нулю
606	Не удалось найти покупателя по указанным данным	В базе данных не найден активный контакт с указанным телефоном и (если передано) ФИО
607	Не переданы дата и время осмотра	Поле transfer_date отсутствует в запросе
607	Не распознаны дата и время осмотра	Значение поля transfer_date не соответствует формату ISO 8601
608	Запись в этот объект недоступна через API «Передача ключей»	В указанном доме (поле house_id) включена настройка "Не выгружать объекты этого дома в API «Передача ключей»"
609	Выбранная дата недоступна для записи	Указанное время в указанном доме уже занято
610	Указанный менеджер не найден	Указанный менеджер не указан в настройке компании «Передача ключей: Сотрудники компании, ответственные за передачу квартир»
611	Дата осмотра не может быть раньше даты готовности	Указанная дата для записи на осмотр является более ранней по отношению к указанной в системе MACRO дате готовности объекта к передаче (плановой или фактической)
612	В указанное время все сотрудники заняты	Все менеджеры компании, ответственные за передачу ключей, заняты в указанное время указанной даты
613	В указанное время менеджер занят	Указанный менеджер занят в указанное время указанной даты
614	Не удалось найти сделку по указанным данным	В базе данных системы MACRO в указанном доме не найден объект в статусе «Сделка проведена» с номером и указанной категорией
501	Не удалось зарезервировать указанную дату	Внутренняя ошибка сервиса ReserveTransferTime при попытке зарезервировать время