Справочник по Home Planner CRM API

Эндпоинты, аутентификация, отправка через вебхуки и структура записи проекта в Home Planner CRM API для Zapier, Make и твоего собственного сервера.

Home Planner CRM API связывает приложение Home Planner с Zapier, Make и твоим собственным сервером. В нём четыре эндпоинта, и все они требуют ключ подключения, а также один вебхук, который отправляет проекты пользователя.
Эта страница предназначена для разработчиков и интеграционных платформ. О том, как настроить отправку проектов прямо в приложении, читай в статье Как отправлять проекты из Home Planner в свою CRM.
Обзор
| Параметр | Значение |
|---|---|
| Базовый URL | https://icandesignapp.com (используй именно этот хост: при редиректе с homeplannerapp.com тело POST-запроса может потеряться) |
| Формат | JSON через HTTPS |
| Аутентификация | Ключ подключения в заголовке X-Api-Key |
| Доставка | Вебхук (REST hook): один POST-запрос на каждый отправленный проект |
| Необходимый тариф | PRO++ (или его бесплатная пробная версия на 14 дней) |
Подключиться можно двумя способами:
- Подключение по ключу — для Zapier и Make. Пользователь выбирает CRM в приложении и копирует ключ, а платформа подписывает свой вебхук с помощью запроса POST /crm/key/hooks. На этой странице описан именно этот способ.
- Подключение по URL — для твоего собственного сервера. Пользователь выбирает в приложении вариант Другая система (свой адрес) и вводит URL-адрес. Ключи и эндпоинты здесь не нужны, а секретный ключ подписи приложение покажет автоматически.
| Метод | Эндпоинт | Назначение |
|---|---|---|
| GET | /crm/key/me | Проверить ключ и вернуть название подключения |
| POST | /crm/key/hooks | Оформить подписку на URL вебхука |
| DELETE | /crm/key/hooks/{id} | Отменить подписку на вебхук |
| GET | /crm/key/sample | Получить пример записи проекта |
Аутентификация
Каждый запрос передаёт ключ подключения в заголовке X-Api-Key. Каждый ключ привязан к одному CRM-подключению в одной учётной записи Home Planner. Никогда не передавай ключ прямо в URL-адресе.
X-Api-Key: hp_live_<accountId>_<connectionId>_<version>_<signature>Пользователь получает ключ в приложении Home Planner:
- Открой Настройки и выбери, куда отправлять проекты.
- Нажми Добавить подключение и выбери HubSpot, Pipedrive, Bitrix24, Salesforce или Google Sheets.
- Нажми Скопировать ключ.
Ключ перестаёт работать, как только пользователь нажимает Новый ключ или удаляет подключение. Любой запрос с отсутствующим, недействительным или заменённым ключом возвращает код 401 с сообщением {"code": "crm_key_invalid"} (исключение — метод DELETE, см. ниже).
GET /crm/key/me
Возвращает подключение, к которому относится ключ. Zapier вызывает этот метод для проверки нового подключения и его присвоения.
curl https://icandesignapp.com/crm/key/me \
-H 'X-Api-Key: hp_live_…'Ответ 200:
{
"connectionId": "65f0c3a2e4b0a1b2c3d4e5f7",
"name": "HubSpot deals",
"system": "hubspot"
}| Поле | Тип | Описание |
|---|---|---|
| connectionId | строка | Идентификатор подключения |
| name | строка | Название подключения из приложения, до 24 символов |
| system | строка | hubspot, pipedrive, bitrix24, salesforce или sheets |
Ошибки: 401 crm_key_invalid. Описание других ошибок см. в разделе «Ошибки» ниже.
POST /crm/key/hooks
Задаёт URL-адрес вебхука, который будет принимать все отправленные через это подключение проекты. Zapier вызывает этот метод при включении Zap.
curl -X POST https://icandesignapp.com/crm/key/hooks \
-H 'X-Api-Key: hp_live_…' \
-H 'Content-Type: application/json' \
-d '{"url": "https://hooks.zapier.com/hooks/standard/123456/abcdef/"}'Ответ 201:
{
"id": "3f2b9c0d1e4a5b6c7d8e9f01"
}Сохрани id: он понадобится тебе для отмены подписки.
- Для каждого подключения доступна только одна подписка: новая подписка автоматически заменяет предыдущий URL-адрес.
- URL-адрес должен начинаться с https://, содержать не более 2048 символов и не иметь в своём составе логина или пароля.
- URL-адреса, ведущие на частные или локальные сети (включая имена хостов, которые в них резолвятся), отклоняются: localhost, 127.*, 10.*, 172.16–31.*, 192.168.* и 169.254.*.
| Статус | code | Значение |
|---|---|---|
| 401 | crm_key_invalid | Ключ отсутствует, недействителен или заменён |
| 422 | crm_url_invalid | URL не начинается с https:// или превышает 2048 символов |
| 422 | crm_url_credentials | URL содержит логин или пароль |
| 422 | crm_url_forbidden | URL указывает на частную или локальную сеть |
Описание других ошибок см. в разделе «Ошибки» ниже.
DELETE /crm/key/hooks/{id}
Удаляет подписку с указанным id. Zapier вызывает этот метод, когда Zap выключается или удаляется.
curl -X DELETE https://icandesignapp.com/crm/key/hooks/3f2b9c0d1e4a5b6c7d8e9f01 \
-H 'X-Api-Key: hp_live_…'Ответ 204 без тела. Ответ также будет 204, если идентификатор не совпадает с текущей подпиской, ключ был заменён или само подключение удалено. Во всех этих случаях удалять уже просто нечего.
Ошибки: 401 crm_key_invalid, если ключ отсутствует или никогда не был действительным. Описание других ошибок см. в разделе «Ошибки» ниже.
GET /crm/key/sample
Возвращает массив с одной тестовой записью проекта в том же формате, что и настоящая доставка. Zapier показывает её поля, чтобы пользователь мог сопоставить их с полями в CRM.
curl https://icandesignapp.com/crm/key/sample \
-H 'X-Api-Key: hp_live_…'Ответ 200: массив с одной записью проекта (см. ниже).
Ошибки: 401 crm_key_invalid. Описание других ошибок см. в разделе «Ошибки» ниже.
Доставка через вебхук
Когда пользователь нажимает Поделиться → Отправить в… в приложении, Home Planner отправляет проект с помощью POST-запроса на зарегистрированный URL-адрес.
| Часть | Значение |
|---|---|
| Метод | POST |
| Content-Type | application/json |
| Тело | Одна запись проекта |
| X-HomePlanner-Delivery | Идентификатор доставки. Он сохраняется при повторных попытках: используй его для отслеживания дубликатов. |
| X-HomePlanner-Signature | t=<время unix в секундах>,v1=<шестнадцатеричный хэш в нижнем регистре>, где v1 = HMAC-SHA256(секретный ключ подписи, t + "." + сырое тело запроса) |
| Твой ответ | Действия Home Planner |
|---|---|
| Любой код 2xx в течение 15 секунд | Доставлено |
| Нет ответа в течение 15 секунд, 5xx, 408 или 429 | Повторные попытки через 1 минуту, 10 минут и 1 час. Если проект так и не доставлен через 2 часа после первой попытки, отправка прекращается, а подключение в приложении помечается статусом «Ошибка». |
| 410 Gone | Подключение по ключу: удаляет подписку; включи Zap снова, чтобы оформить её заново. Подключение по URL: обрабатывается аналогично любому другому коду 4xx |
| Любой другой код 4xx, редирект или ошибка сертификата | Без повторных попыток; приложение помечает подключение статусом «Ошибка» |
Каждая доставка подписывается. Приложение показывает секретный ключ подписи только при подключении по URL. Пошаговую инструкцию по проверке подписи см. в статье Как отправлять проекты из Home Planner в свою CRM.
Когда у пользователя заканчивается подписка PRO++ или её бесплатный пробный период, приложение прекращает отправку проектов. Эндпоинты продолжают отвечать, поэтому Zap остаётся активным, но новые проекты не поступают, пока подписка не будет продлена.
Запись проекта
Этот формат используется во всех доставках и в тестовом эндпоинте. Цены и итоговые суммы совпадают со сметой проекта в приложении. В Zapier у записи также есть поле id — это копия client_reference_id, которая отображается как Send ID.
{
"client_reference_id": "sample_0d4f1c2b9e7a",
"planNumber": "000000000000000000000000",
"planName": "Sample project",
"revisionUrl": "https://share.roomplannerapp.com/all/project/000000000000000000000000",
"revisionNumber": "1",
"updated": "2026-10-01T12:00:00.000Z",
"created": "2026-09-28T09:30:00.000Z",
"rooms": [
{
"roomNumber": "6f1d2c3b4a5e6f708192a3b4c5d6e7f8",
"roomName": "Living room",
"items": [
{
"itemNumber": "SOFA-1042",
"quantity": 1,
"imageURL": "https://files.icandesignapp.com/sample/sofa.jpg",
"components": [
{
"itemNumber": "CUSH-17",
"quantity": 2,
"imageURL": "",
"name": "Cushion",
"price": 25,
"currency": "USD",
"total": 50,
"price_source": "estimate",
"source": "homeplanner"
}
],
"name": "Sofa Oslo",
"price": 899,
"currency": "USD",
"total": 899,
"price_source": "company",
"source": "company",
"note": null
},
{
"itemNumber": "Floor_Oak_01",
"quantity": 1,
"imageURL": "",
"name": "Oak flooring",
"price": 540,
"currency": "USD",
"total": 540,
"price_source": "estimate",
"source": "homeplanner",
"note": null,
"area": 18
}
],
"roomType": "LivingRoom",
"area": 18,
"height": 2.7,
"width": 4,
"depth": 4.5
}
],
"integration": "custom",
"totals": {
"items": 2,
"sum": 1489,
"currency": "USD"
},
"warning": null,
"pdfUrl": "https://files.icandesignapp.com/sample/plan.crm.pdf",
"productsText": "Living room:\n- Sofa Oslo (SOFA-1042): 1 × 899.00 = 899.00 USD\n - Cushion (CUSH-17): 2 × 25.00 = 50.00 USD\n- Oak flooring (Floor_Oak_01): 1 × 540.00 = 540.00 USD\n\nTotal: 1489.00 USD"
}| Поле | Тип | Описание |
|---|---|---|
| client_reference_id | строка | Уникальный идентификатор этой отправки |
| planNumber | строка | Идентификатор проекта |
| planName | строка | Название проекта |
| revisionUrl | строка | Публичная ссылка на проект |
| revisionNumber | строка | Редакция проекта |
| created, updated | строка, ISO 8601 | Время создания и последнего сохранения проекта |
| rooms[] | массив | roomNumber, roomName, roomType, area (м²), height, width, depth (м), items |
| rooms[].items[] | массив | itemNumber (артикул), name, quantity, price, currency, total, price_source, source, imageURL, note (заметка пользователя о товаре или null), area (м², для материалов), components[] (составные части товара со всеми теми же полями, где quantity — это количество для всех единиц товара, а также quantityPerItem — количество на одну единицу; в тестовой записи поле quantityPerItem опускается) |
| price_source | строка | company (цена из каталога компании) или estimate (расчётная цена Home Planner) |
| source | строка | company (товар из каталога компании) или homeplanner (каталог Home Planner) |
| totals | объект | items: количество основных позиций списка (компоненты не учитываются); sum: итоговая сумма сметы с учётом компонентов; currency: код валюты |
| pdfUrl | строка или null | Ссылка на план помещения в формате PDF; файл доступен в течение 7 дней |
| productsText | строка | Полная смета в виде обычного текста |
| warning | строка или null | Например: "2 item(s) without SKU were sent with a Home Planner code" |
| integration | строка | Всегда "custom" |
Лимиты на количество запросов
| Область действия | Лимит |
|---|---|
| Один ключ подключения | 30 запросов в минуту, 500 в день |
| Запросы с недействительным ключом (для одного IP-адреса) | 300 в минуту, 5000 в день |
При превышении лимита API возвращает код 429 с сообщением {"code": "crm_throttled"}.
Ошибки
Каждая ошибка представляет собой JSON-объект с полем code, например {"code": "crm_key_invalid"}.
| Статус | code | Значение |
|---|---|---|
| 401 | crm_key_invalid | Ключ отсутствует, недействителен или заменён |
| 422 | crm_url_invalid, crm_url_credentials, crm_url_forbidden | URL-адрес вебхука отклонён |
| 429 | crm_throttled | Превышен лимит на количество запросов |
| 503 | crm_unavailable | Временный сбой сервера; повтори попытку позже |
Техническая поддержка
Если у тебя есть вопросы по работе API, пиши нам на [email protected].
Уведомление о товарных знаках. Zapier, Make, HubSpot, Pipedrive, Bitrix24, Salesforce и Google Sheets являются товарными знаками их законных владельцев. Home Planner работает независимо от этих компаний и не связан с ними отношениями партнерства, спонсорства или одобрения.
Попробуй на своем проекте
Бесплатное приложение для планировки комнат и дизайна интерьера


