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

Для получения возможности использовать функционал api по передаче ключей предварительно необходимо настроить /manual/integracii/sait_kompanii/integracija_s_saitom.md интеграцию вашего сайта с MACRO.

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

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

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

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

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

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

Метод: GET или POST

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

Параметр
Обяз.
Пример
Описание

time

Да

1234567890

unix timestamp запроса

domain

Да

"вашсайт.рф"

Домен, зарегистрированный в MacroCRM

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 дома

data.houses[].title

Название дома

data.houses[].flats

Массив с номерами квартир готовых к передаче

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

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

Метод: GET

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

Параметр
Обяз.
Пример
Описание

time

Да

1234567890

unix timestamp запроса

domain

Да

"вашсайт.рф"

Домен, зарегистрированный в MacroCRM

token

Да

md5(domain+time+app_secret)

пример на php: $token = md5($domain . time() . $app_secret)

transfer_date

Да

"2020-06-11T00:00:00+05:00"

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

house_id

Да

123

Идентификатор дома, по которому нужно вернуть список Параметр обязательный, если компания для каждого дома использует отдельный график передачи квартир

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

{
    "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). Например: 2025-08-20T10:00:00+03:000.

phone

string

Да

"+7 (900) 000-000"

Контактный номер телефона покупателя. Номер будет приведен к формату +7.XXXXXXXXXX для поиска в базе данных.

name

string

Да

"Иванов Иван Иванович"

Полное имя покупателя. Используется для более точного поиска контакта в базе.

flat_num

string/integer

Да

"1.9-7-4"

Номер объекта недвижимости (квартиры, парковочного места и т.д.).

house_id

integer

Да

8561992

Уникальный идентификатор дома (здания), в котором находится объект недвижимости.

category

string

Да

"flat"

Категория объекта, в который требуется добавить запись на осмотр.

Квартиры: flat Парковки: garage Кладовые: storageroom Коммерческие помещения: comm

Если категория не будет передана, то запись на осмотр добавится в первый найденный объект с совпадающим номером.

manager_id

integer

Да

"86998"

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

token

integer

Да

1

пример на php: $token = md5($domain . time() . $app_secret)

time

intege

Да

1

unix timestamp запроса.

please

intege

Да

1

один из ключей в объекте.

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

{
    "domain": "вашсайт.рф",
    "transfer_date": "2025-08-27T10:00:00+03:00",
    "phone": "+7 (900) 000-000",
    "name": "Иванов Иван  Иванович",
    "flat_num": "1.9-7-4",
    "house_id": 8561992,
    "category": "flat",
    "manager_id": 86998,
    "token": 1,
    "time": 1,
    "please": 1
}

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

{
    "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 отсутствует или равно нулю.

605

Выбранная дата уже зарезервирована

Указанное время в указанном доме уже занято.

606

Не удалось найти покупателя по указанным данным

В базе данных не найден активный контакт с указанным телефоном и (если передано) ФИО.

607

Не переданы дата и время осмотра

Поле transfer_date отсутствует в запросе.

607

Не распознаны дата и время осмотра

Значение поля transfer_date не соответствует формату ISO 8601.

610

Указанный менеджер не найден

Указанный менеджер не указан в настройке компании "Передача ключей: Сотрудники компании, ответственные за передачу квартир"

501

Не удалось зарезервировать указанную дату

Внутренняя ошибка сервиса ReserveTransferTime при попытке зарезервировать время.

Last updated