Home Planner
Назад в справочный центрИнструкции

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

Home Planner
Home PlannerКоманда приложения · 28 октября 2026

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

Приложение Home Planner отправляет проект дизайна комнаты через Zapier в HubSpot, Salesforce, Google Таблицы и Pipedrive.

Home Planner CRM API связывает приложение Home Planner с Zapier, Make и твоим собственным сервером. В нём четыре эндпоинта, и все они требуют ключ подключения, а также один вебхук, который отправляет проекты пользователя.

Эта страница предназначена для разработчиков и интеграционных платформ. О том, как настроить отправку проектов прямо в приложении, читай в статье Как отправлять проекты из Home Planner в свою CRM.

Обзор

ПараметрЗначение
Базовый URLhttps://icandesignapp.com (используй именно этот хост: при редиректе с homeplannerapp.com тело POST-запроса может потеряться)
ФорматJSON через HTTPS
АутентификацияКлюч подключения в заголовке X-Api-Key
ДоставкаВебхук (REST hook): один POST-запрос на каждый отправленный проект
Необходимый тарифPRO++ (или его бесплатная пробная версия на 14 дней)

Подключиться можно двумя способами:

  1. Подключение по ключу — для Zapier и Make. Пользователь выбирает CRM в приложении и копирует ключ, а платформа подписывает свой вебхук с помощью запроса POST /crm/key/hooks. На этой странице описан именно этот способ.
  2. Подключение по 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-адресе.

yamlyaml
X-Api-Key: hp_live_<accountId>_<connectionId>_<version>_<signature>

Пользователь получает ключ в приложении Home Planner:

  1. Открой Настройки и выбери, куда отправлять проекты.
  2. Нажми Добавить подключение и выбери HubSpot, Pipedrive, Bitrix24, Salesforce или Google Sheets.
  3. Нажми Скопировать ключ.

Ключ перестаёт работать, как только пользователь нажимает Новый ключ или удаляет подключение. Любой запрос с отсутствующим, недействительным или заменённым ключом возвращает код 401 с сообщением {"code": "crm_key_invalid"} (исключение — метод DELETE, см. ниже).

GET /crm/key/me

Возвращает подключение, к которому относится ключ. Zapier вызывает этот метод для проверки нового подключения и его присвоения.

bashbash
curl https://icandesignapp.com/crm/key/me \
  -H 'X-Api-Key: hp_live_…'

Ответ 200:

jsonjson
{
  "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.

bashbash
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:

jsonjson
{
  "id": "3f2b9c0d1e4a5b6c7d8e9f01"
}

Сохрани id: он понадобится тебе для отмены подписки.

  • Для каждого подключения доступна только одна подписка: новая подписка автоматически заменяет предыдущий URL-адрес.
  • URL-адрес должен начинаться с https://, содержать не более 2048 символов и не иметь в своём составе логина или пароля.
  • URL-адреса, ведущие на частные или локальные сети (включая имена хостов, которые в них резолвятся), отклоняются: localhost, 127.*, 10.*, 172.16–31.*, 192.168.* и 169.254.*.
СтатусcodeЗначение
401crm_key_invalidКлюч отсутствует, недействителен или заменён
422crm_url_invalidURL не начинается с https:// или превышает 2048 символов
422crm_url_credentialsURL содержит логин или пароль
422crm_url_forbiddenURL указывает на частную или локальную сеть

Описание других ошибок см. в разделе «Ошибки» ниже.

DELETE /crm/key/hooks/{id}

Удаляет подписку с указанным id. Zapier вызывает этот метод, когда Zap выключается или удаляется.

bashbash
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.

bashbash
curl https://icandesignapp.com/crm/key/sample \
  -H 'X-Api-Key: hp_live_…'

Ответ 200: массив с одной записью проекта (см. ниже).

Ошибки: 401 crm_key_invalid. Описание других ошибок см. в разделе «Ошибки» ниже.

Доставка через вебхук

Когда пользователь нажимает Поделиться → Отправить в… в приложении, Home Planner отправляет проект с помощью POST-запроса на зарегистрированный URL-адрес.

ЧастьЗначение
МетодPOST
Content-Typeapplication/json
ТелоОдна запись проекта
X-HomePlanner-DeliveryИдентификатор доставки. Он сохраняется при повторных попытках: используй его для отслеживания дубликатов.
X-HomePlanner-Signaturet=<время 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.

project-record.jsonjson
{
  "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Значение
401crm_key_invalidКлюч отсутствует, недействителен или заменён
422crm_url_invalid, crm_url_credentials, crm_url_forbiddenURL-адрес вебхука отклонён
429crm_throttledПревышен лимит на количество запросов
503crm_unavailableВременный сбой сервера; повтори попытку позже

Техническая поддержка

Если у тебя есть вопросы по работе API, пиши нам на [email protected].

Уведомление о товарных знаках. Zapier, Make, HubSpot, Pipedrive, Bitrix24, Salesforce и Google Sheets являются товарными знаками их законных владельцев. Home Planner работает независимо от этих компаний и не связан с ними отношениями партнерства, спонсорства или одобрения.

Home Planner

Попробуй на своем проекте

Бесплатное приложение для планировки комнат и дизайна интерьера