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

Для получения возможности использовать функционал API по передаче ключей предварительно необходимо настроить [интеграцию Вашего сайта ](https://docs.macrodigital.ru/manual/platforma-macro/api/integracija_s_saitom)с MACRO.

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

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

1. Ваш сервис запрашивает список объектов, которые готовы к передаче. API в ответ возвращает список из номеров объектов, сгруппированный по домам. В выборку попадают объекты в статусе <mark style="background-color:blue;">Сделка проведена</mark> с указанной фактической датой готовности к передаче.
2. Пользователь выбирает интересующий его дом и удобную дату. Сервис отправляет эти данные в API и в ответ получает список свободных временных промежутков для записи на передачу.
3. Сервис отправляет в API запрос на бронирование времени под передачу.

## API 2.0

С выпуском версии <mark style="background-color:yellow;">**MacroAPI v2**</mark> для работы с функционалом передачи ключей обязательным требованием стало использование <mark style="background-color:yellow;">**API-ключей**</mark> для аутентификации и авторизации запросов. Подробнее о там как добавить <mark style="background-color:yellow;">**API-ключ**</mark> Вы можете ознакомится в [статье](https://docs.macrodigital.ru/manual/platforma-macro/api/apps).

О том какие параметры запросов используются в функционале API по передаче ключей, Вы можете узнать в разделе [EstateTransfer](https://api.macroserver.ru/docs/api/v2/#tag/EstateTransfer) документации.

## API 1.0

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

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

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

Метод: **GET** или **POST**

<table data-full-width="false"><thead><tr><th width="119.60009765625">Параметр</th><th width="84.5999755859375">Обяз.</th><th width="161.5999755859375">Пример</th><th>Описание</th></tr></thead><tbody><tr><td>time</td><td>Да</td><td>1234567890</td><td>Unix timestamp запроса</td></tr><tr><td>domain</td><td>Да</td><td>"вашсайт.рф"</td><td>Домен, зарегистрированный в системе MACRO</td></tr><tr><td>token</td><td>Да</td><td>md5(domain+time+app_secret)</td><td><p>Пример на PHP:</p><p><code>$token = md5($domain . time() . $app_secret)</code></p></td></tr><tr><td>category</td><td>Да</td><td>storageroom</td><td>Ограничивает выборку объектов с учётом указанной категории недвижимости: <br>— квартиры: flat <br>— машино-места: garage <br>— кладовые: storageroom<br>— коммерческие помещения: comm</td></tr></tbody></table>

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

{% code fullWidth="false" %}

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

{% endcode %}

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

{% code fullWidth="false" %}

```json
{
    "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": "Выполнено"
}
```

{% endcode %}

<table data-full-width="false"><thead><tr><th width="169.5999755859375">Параметр</th><th>Описание</th></tr></thead><tbody><tr><td>status_code</td><td>Код ответа сервера</td></tr><tr><td>message</td><td>В случае ошибки содержит её описание</td></tr><tr><td>data.houses</td><td>Массив со списком домов</td></tr><tr><td>data.houses[].id</td><td>ID дома в системе MACRO</td></tr><tr><td>data.houses[].title</td><td>Название дома в системе MACRO</td></tr><tr><td>data.houses[].flats</td><td>Массив с номерами квартир, готовых к передаче</td></tr></tbody></table>

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

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

[https://api.macrocrm.ru/estate/transfer/getFreeTimes/](https://api.macrocrm.ru/estate/transfer/getReadyFlats/)

Метод: **GET**

<table data-full-width="false"><thead><tr><th width="129.800048828125">Параметр</th><th width="84.5999755859375">Обяз.</th><th width="261">Пример</th><th>Описание</th></tr></thead><tbody><tr><td>time</td><td>Да</td><td>1234567890</td><td>Unix timestamp запроса</td></tr><tr><td>domain</td><td>Да</td><td>"вашсайт.рф"</td><td>Домен, зарегистрированный в системе MACRO</td></tr><tr><td>token</td><td>Да</td><td>md5(domain+time+app_secret)</td><td><p>Пример на PHP:</p><p><code>$token = md5($domain . time() . $app_secret)</code></p></td></tr><tr><td>transfer_date</td><td>Да</td><td>"2020-06-11T00:00:00+05:00"</td><td>Дата, для которой нужно вернуть список доступных временных промежутков для записи на передачу квартир. Должна быть в формате ISO 8601 (DATE_ATOM). </td></tr><tr><td>house_id</td><td>Да</td><td>123</td><td>ID дома в системе MACRO, по которому нужно вернуть список. Параметр обязательный, если Вы для каждого дома используете отдельный график передачи квартир</td></tr></tbody></table>

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

{% code fullWidth="false" %}

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

{% endcode %}

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

{% code fullWidth="false" %}

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

{% endcode %}

<table><thead><tr><th width="128.199951171875">Параметр</th><th>Описание</th></tr></thead><tbody><tr><td>status_code</td><td>Код ответа сервера</td></tr><tr><td>message</td><td>В случае ошибки содержит её описание</td></tr><tr><td>data</td><td>Массив со списком доступных временных промежутков</td></tr></tbody></table>

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

{% hint style="warning" %}
**Важно!** Убедитесь что в настройке компании «Передача ключей: Сотрудники компании, ответственные за передачу квартир» указан хотя бы один ответственный менеджер.
{% endhint %}

<figure><img src="https://2409287958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfkymnT1WRuXnrJRm6ZIO%2Fuploads%2FCjTjMeCiTAWDHLzIiT2B%2FkbdF3lbzph.png?alt=media&#x26;token=7de18b79-a64f-4965-9e68-61ccdb0a5808" alt=""><figcaption></figcaption></figure>

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

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

Метод: POST

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

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

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

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

{% code fullWidth="true" %}

```json
{
    "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,
}
```

{% endcode %}

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

{% code fullWidth="false" %}

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

{% endcode %}

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

{% code fullWidth="false" %}

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

{% endcode %}

<table><thead><tr><th width="130.00006103515625">Параметр</th><th>Описание</th></tr></thead><tbody><tr><td>status_code</td><td>Код ответа сервера</td></tr><tr><td>error</td><td>Указание на наличие ошибки</td></tr><tr><td>success</td><td>Указание на успешное выполнение запроса</td></tr><tr><td>message</td><td>Описание ошибки или сообщение об успешном выполнении запроса</td></tr></tbody></table>

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

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