Home Planner
Kembali ke Pusat bantuanPanduan penggunaan

Referensi API CRM Home Planner

Home Planner
Home PlannerTim Aplikasi · October 28, 2026

Titik akhir, otentikasi, pengiriman webhook, dan rekaman proyek API CRM Home Planner yang digunakan oleh Zapier, Make, dan server Anda sendiri.

Aplikasi Home Planner mengirimkan proyek desain ruangan melalui Zapier ke HubSpot, Salesforce, Google Sheets, dan Pipedrive

API CRM Home Planner menghubungkan aplikasi Home Planner ke Zapier, Make, dan server Anda sendiri. API ini memiliki empat titik akhir (endpoint) yang diotentikasi menggunakan kunci koneksi, serta satu webhook yang mengirimkan setiap proyek yang dikirim oleh pengguna.

Halaman ini ditujukan bagi pengembang dan platform integrasi. Untuk mengatur pengiriman proyek di dalam aplikasi, baca Cara mengirim proyek dari Home Planner ke CRM Anda.

Ringkasan

ItemNilai
URL dasarhttps://icandesignapp.com (gunakan host ini: pengalihan dari homeplannerapp.com dapat menghapus isi pesan POST)
FormatJSON melalui HTTPS
OtentikasiKunci koneksi di header X-Api-Key
PengirimanWebhook (hook REST): satu POST per proyek yang dikirim
Paket yang diperlukanPRO++ (atau uji coba gratis 14 harinya)

Terdapat dua cara untuk terhubung:

  1. Koneksi kunci — untuk Zapier dan Make. Pengguna memilih CRM di dalam aplikasi dan menyalin kuncinya; platform mendaftarkan webhook-nya dengan POST /crm/key/hooks. Halaman ini menjelaskan cara tersebut.
  2. Koneksi URL — untuk server Anda sendiri. Pengguna memilih Sistem lain (URL Anda) di dalam aplikasi lalu memasukkan URL-nya di sana. Tidak diperlukan kunci maupun titik akhir, dan aplikasi akan menampilkan rahasia penandatanganan.
MetodeTitik akhirTujuan
GET/crm/key/meValidasi kunci dan kembalikan nama koneksi
POST/crm/key/hooksDaftarkan URL webhook
DELETE/crm/key/hooks/{id}Hapus pendaftaran webhook
GET/crm/key/sampleDapatkan contoh rekaman proyek

Otentikasi

Setiap permintaan menyertakan kunci koneksi di dalam header X-Api-Key. Setiap kunci terikat pada satu koneksi CRM di satu akun Home Planner. Jangan pernah mencantumkan kunci di dalam URL.

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

Pengguna mendapatkan kunci tersebut di dalam aplikasi Home Planner:

  1. Buka Pengaturan lalu pilih tujuan pengiriman proyek.
  2. Pilih Tambah koneksi dan pilih HubSpot, Pipedrive, Bitrix24, Salesforce, atau Google Sheets.
  3. Pilih Salin kunci.

Kunci akan berhenti berfungsi saat pengguna memilih Kunci baru atau menghapus koneksi. Setiap permintaan dengan kunci yang hilang, tidak valid, atau telah diganti akan mengembalikan 401 dengan {"code": "crm_key_invalid"} (pengecualian untuk DELETE, lihat di bawah).

GET /crm/key/me

Mengembalikan koneksi pemilik kunci tersebut. Zapier memanggilnya untuk menguji koneksi baru dan memberinya label.

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

Respons 200:

jsonjson
{
  "connectionId": "65f0c3a2e4b0a1b2c3d4e5f7",
  "name": "HubSpot deals",
  "system": "hubspot"
}
BidangTipeDeskripsi
connectionIdstringID Koneksi
namestringNama koneksi dari aplikasi, hingga 24 karakter
systemstringhubspot, pipedrive, bitrix24, salesforce, atau sheets

Kesalahan: 401 crm_key_invalid. Kesalahan lainnya: lihat bagian Kesalahan di bawah.

POST /crm/key/hooks

Menentukan URL webhook yang menerima setiap proyek yang dikirim melalui koneksi ini. Zapier memanggilnya saat Zap diaktifkan.

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/"}'

Respons 201:

jsonjson
{
  "id": "3f2b9c0d1e4a5b6c7d8e9f01"
}

Simpan id: Anda membutuhkannya untuk menghapus pendaftaran.

  • Satu pendaftaran per koneksi: pendaftaran baru akan menggantikan URL sebelumnya.
  • URL harus diawali dengan https://, panjangnya maksimum 2048 karakter, dan tidak boleh berisi nama pengguna atau kata sandi.
  • URL yang mengarah ke jaringan pribadi atau lokal, termasuk nama host yang mengarah ke sana, akan ditolak: localhost, 127.*, 10.*, 172.16–31.*, 192.168.*, dan 169.254.*.
StatuskodeArti
401crm_key_invalidKunci hilang, tidak valid, atau telah diganti
422crm_url_invalidBukan URL https://, atau lebih panjang dari 2048 karakter
422crm_url_credentialsURL berisi nama pengguna atau kata sandi
422crm_url_forbiddenURL mengarah ke jaringan pribadi atau lokal

Kesalahan lainnya: lihat bagian Kesalahan di bawah.

DELETE /crm/key/hooks/{id}

Menghapus pendaftaran dengan id ini. Zapier memanggilnya saat Zap dimatikan atau dihapus.

bashbash
curl -X DELETE https://icandesignapp.com/crm/key/hooks/3f2b9c0d1e4a5b6c7d8e9f01 \
  -H 'X-Api-Key: hp_live_…'

Respons 204 tanpa isi pesan. Respons juga berupa 204 jika ID tidak cocok dengan pendaftaran saat ini, kunci telah diganti, atau koneksi telah dihapus. Dalam setiap kasus tersebut, tidak ada lagi yang perlu dihapus.

Kesalahan: 401 crm_key_invalid untuk kunci yang hilang atau kunci yang tidak pernah valid. Kesalahan lainnya: lihat bagian Kesalahan di bawah.

GET /crm/key/sample

Mengembalikan array berisi satu contoh rekaman proyek dalam format yang sama dengan pengiriman sebenarnya. Zapier menampilkan bidang-bidangnya agar pengguna dapat memetakkannya ke bidang CRM.

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

Respons 200: array berisi satu rekaman proyek (di bawah).

Kesalahan: 401 crm_key_invalid. Kesalahan lainnya: lihat bagian Kesalahan di bawah.

Pengiriman webhook

Saat pengguna memilih Bagikan → Kirim ke … di dalam aplikasi, Home Planner akan memposting proyek ke URL yang terdaftar.

BagianNilai
MetodePOST
Content-Typeapplication/json
Isi pesanSatu rekaman proyek
X-HomePlanner-DeliveryID pengiriman. Nilainya tetap sama pada percobaan ulang: gunakan ini untuk mendeteksi duplikat.
X-HomePlanner-Signaturet=<waktu unix dalam detik>,v1=<heksadesimal huruf kecil>, dengan v1 = HMAC-SHA256(rahasia penandatanganan, t + "." + isi pesan mentah)
Respons AndaTindakan Home Planner
Respons 2xx apa pun dalam 15 detikTerkirim
Tidak ada respons dalam 15 detik, 5xx, 408, atau 429Mencoba ulang setelah 1 menit, 10 menit, dan 1 jam. Jika proyek tetap belum terkirim 2 jam setelah percobaan pertama, pengulangan akan dihentikan dan aplikasi menandai status koneksi sebagai Kesalahan.
410 GoneKoneksi kunci: menghapus pendaftaran; aktifkan kembali Zap untuk mendaftar ulang. Koneksi URL: sama seperti respons 4xx lainnya
Respons 4xx lainnya, pengalihan, atau kesalahan sertifikatTidak ada percobaan ulang; aplikasi menandai status koneksi sebagai Kesalahan

Setiap pengiriman telah ditandatangani. Aplikasi hanya menampilkan rahasia penandatanganan untuk koneksi URL. Untuk langkah verifikasi tanda tangan, baca Cara mengirim proyek dari Home Planner ke CRM Anda.

Saat masa berlangganan PRO++ atau uji coba gratis pengguna berakhir, aplikasi akan berhenti mengirimkan proyek. Titik akhir tetap merespons sehingga Zap tetap aktif tetapi tidak menerima proyek baru sampai pengguna memperbaruinya.

Rekaman proyek

Setiap pengiriman dan titik akhir sampel menggunakan format ini. Harga dan total sesuai dengan estimasi proyek di dalam aplikasi. Di Zapier, rekaman juga memiliki bidang id: salinan dari client_reference_id yang ditampilkan sebagai ID Pengiriman.

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"
}
BidangTipeDeskripsi
client_reference_idstringID unik dari pengiriman ini
planNumberstringID proyek
planNamestringNama proyek
revisionUrlstringTautan publik ke proyek
revisionNumberstringRevisi proyek
dibuat, diperbaruistring, ISO 8601Waktu proyek dibuat dan terakhir disimpan
rooms[]arrayroomNumber, roomName, roomType, area (m²), height, width, depth (m), items
rooms[].items[]arrayitemNumber (SKU), name, quantity, price, currency, total, price_source, source, imageURL, note (catatan pengguna tentang item, atau null), area (m², untuk material), components[] (bagian dari item: bidang yang sama, di mana quantity adalah jumlah untuk semua unit item, ditambah quantityPerItem, yaitu jumlah per unit; sampel menghilangkan quantityPerItem)
price_sourcestringcompany (harga dari katalog perusahaan) atau estimate (estimasi Home Planner)
sourcestringcompany (produk dari katalog perusahaan) atau homeplanner (katalog Home Planner)
totalsobjectitems: jumlah item baris tingkat teratas (komponen tidak dihitung); sum: total estimasi, termasuk komponen; currency: kode mata uang
pdfUrlstring atau nullTautan ke PDF denah lantai; file tersedia selama 7 hari
productsTextstringEstimasi lengkap dalam bentuk teks biasa
warningstring atau nullSebagai contoh: "2 item tanpa SKU dikirim dengan kode Home Planner"
integrasistringSelalu "custom"

Batas laju

CakupanBatas
Satu kunci koneksi30 permintaan per menit, 500 per hari
Permintaan dengan kunci tidak valid, per alamat IP300 per menit, 5000 per hari

Saat batas terlampaui, API mengembalikan 429 dengan {"code": "crm_throttled"}.

Kesalahan

Setiap kesalahan berupa JSON dengan bidang code, misalnya {"code": "crm_key_invalid"}.

StatuskodeArti
401crm_key_invalidKunci hilang, tidak valid, atau telah diganti
422crm_url_invalid, crm_url_credentials, crm_url_forbiddenURL webhook ditolak
429crm_throttledBatas laju tercapai
503crm_unavailableMasalah server sementara; coba lagi nanti

Dukungan

Pertanyaan seputar API: [email protected].

Pemberitahuan merek dagang. Zapier, Make, HubSpot, Pipedrive, Bitrix24, Salesforce, dan Google Sheets adalah merek dagang dari pemiliknya masing-masing. Home Planner berdiri sendiri dan tidak didukung oleh, disponsori oleh, atau terafiliasi dengan perusahaan-perusahaan tersebut.

Home Planner

Coba di proyek Anda sendiri

Aplikasi desain interior dan perencana ruangan gratis