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

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

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

Ваш сервис запрашивает список объектов, которые готовы к передаче. API в ответ возвращает список из номеров объектов, сгруппированный по домам. В выборку попадают объекты в статусе Сделка проведена с указанной фактической датой готовности к передаче.
Пользователь выбирает интересующий его дом и удобную дату. Сервис отправляет эти данные в API и в ответ получает список свободных временных промежутков для записи на передачу.
Сервис отправляет в 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

Да

"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": "+7 (900) 000-000",
    "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 отсутствует или равно нулю.

605

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

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

606

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

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

607

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

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

607

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

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

610

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

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

501

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

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

Last updated 6 days ago