Referensi API CRM Home Planner

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

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
| Item | Nilai |
|---|---|
| URL dasar | https://icandesignapp.com (gunakan host ini: pengalihan dari homeplannerapp.com dapat menghapus isi pesan POST) |
| Format | JSON melalui HTTPS |
| Otentikasi | Kunci koneksi di header X-Api-Key |
| Pengiriman | Webhook (hook REST): satu POST per proyek yang dikirim |
| Paket yang diperlukan | PRO++ (atau uji coba gratis 14 harinya) |
Terdapat dua cara untuk terhubung:
- 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.
- 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.
| Metode | Titik akhir | Tujuan |
|---|---|---|
| GET | /crm/key/me | Validasi kunci dan kembalikan nama koneksi |
| POST | /crm/key/hooks | Daftarkan URL webhook |
| DELETE | /crm/key/hooks/{id} | Hapus pendaftaran webhook |
| GET | /crm/key/sample | Dapatkan 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.
X-Api-Key: hp_live_<accountId>_<connectionId>_<version>_<signature>Pengguna mendapatkan kunci tersebut di dalam aplikasi Home Planner:
- Buka Pengaturan lalu pilih tujuan pengiriman proyek.
- Pilih Tambah koneksi dan pilih HubSpot, Pipedrive, Bitrix24, Salesforce, atau Google Sheets.
- 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.
curl https://icandesignapp.com/crm/key/me \
-H 'X-Api-Key: hp_live_…'Respons 200:
{
"connectionId": "65f0c3a2e4b0a1b2c3d4e5f7",
"name": "HubSpot deals",
"system": "hubspot"
}| Bidang | Tipe | Deskripsi |
|---|---|---|
| connectionId | string | ID Koneksi |
| name | string | Nama koneksi dari aplikasi, hingga 24 karakter |
| system | string | hubspot, 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.
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:
{
"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.*.
| Status | kode | Arti |
|---|---|---|
| 401 | crm_key_invalid | Kunci hilang, tidak valid, atau telah diganti |
| 422 | crm_url_invalid | Bukan URL https://, atau lebih panjang dari 2048 karakter |
| 422 | crm_url_credentials | URL berisi nama pengguna atau kata sandi |
| 422 | crm_url_forbidden | URL 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.
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.
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.
| Bagian | Nilai |
|---|---|
| Metode | POST |
| Content-Type | application/json |
| Isi pesan | Satu rekaman proyek |
| X-HomePlanner-Delivery | ID pengiriman. Nilainya tetap sama pada percobaan ulang: gunakan ini untuk mendeteksi duplikat. |
| X-HomePlanner-Signature | t=<waktu unix dalam detik>,v1=<heksadesimal huruf kecil>, dengan v1 = HMAC-SHA256(rahasia penandatanganan, t + "." + isi pesan mentah) |
| Respons Anda | Tindakan Home Planner |
|---|---|
| Respons 2xx apa pun dalam 15 detik | Terkirim |
| Tidak ada respons dalam 15 detik, 5xx, 408, atau 429 | Mencoba 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 Gone | Koneksi kunci: menghapus pendaftaran; aktifkan kembali Zap untuk mendaftar ulang. Koneksi URL: sama seperti respons 4xx lainnya |
| Respons 4xx lainnya, pengalihan, atau kesalahan sertifikat | Tidak 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.
{
"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"
}| Bidang | Tipe | Deskripsi |
|---|---|---|
| client_reference_id | string | ID unik dari pengiriman ini |
| planNumber | string | ID proyek |
| planName | string | Nama proyek |
| revisionUrl | string | Tautan publik ke proyek |
| revisionNumber | string | Revisi proyek |
| dibuat, diperbarui | string, ISO 8601 | Waktu proyek dibuat dan terakhir disimpan |
| rooms[] | array | roomNumber, roomName, roomType, area (m²), height, width, depth (m), items |
| rooms[].items[] | array | itemNumber (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_source | string | company (harga dari katalog perusahaan) atau estimate (estimasi Home Planner) |
| source | string | company (produk dari katalog perusahaan) atau homeplanner (katalog Home Planner) |
| totals | object | items: jumlah item baris tingkat teratas (komponen tidak dihitung); sum: total estimasi, termasuk komponen; currency: kode mata uang |
| pdfUrl | string atau null | Tautan ke PDF denah lantai; file tersedia selama 7 hari |
| productsText | string | Estimasi lengkap dalam bentuk teks biasa |
| warning | string atau null | Sebagai contoh: "2 item tanpa SKU dikirim dengan kode Home Planner" |
| integrasi | string | Selalu "custom" |
Batas laju
| Cakupan | Batas |
|---|---|
| Satu kunci koneksi | 30 permintaan per menit, 500 per hari |
| Permintaan dengan kunci tidak valid, per alamat IP | 300 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"}.
| Status | kode | Arti |
|---|---|---|
| 401 | crm_key_invalid | Kunci hilang, tidak valid, atau telah diganti |
| 422 | crm_url_invalid, crm_url_credentials, crm_url_forbidden | URL webhook ditolak |
| 429 | crm_throttled | Batas laju tercapai |
| 503 | crm_unavailable | Masalah 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.
Coba di proyek Anda sendiri
Aplikasi desain interior dan perencana ruangan gratis


