Home Planner CRM API Referansı

Zapier, Make ve kendi sunucun tarafından kullanılan Home Planner CRM API'sine ait uç noktalar, kimlik doğrulama, web kancası iletimi ve proje kaydı detayları.

Home Planner CRM API'si; Home Planner uygulamasını Zapier, Make ve kendi sunucuna bağlar. Tümü bir bağlantı anahtarıyla doğrulanan dört uç noktaya ve kullanıcının gönderdiği her projeyi ileten bir web kancasına sahiptir.
Bu sayfa geliştiriciler ve entegrasyon platformları içindir. Uygulama içinde proje gönderme işlevini kurmak için Projeler Home Planner'dan CRM sistemine nasıl gönderilir kılavuzuna göz atabilirsin.
Genel Bakış
| Öğe | Değer |
|---|---|
| Kök URL | https://icandesignapp.com (bu sunucu adını kullan: homeplannerapp.com adresinden yapılan yönlendirmeler POST gövdesini düşürebilir) |
| Biçim | HTTPS üzerinden JSON |
| Kimlik doğrulama | X-Api-Key üst bilgisinde bağlantı anahtarı |
| İletim | Web kancası (REST hook): gönderilen proje başına bir POST |
| Gerekli plan | PRO++ (veya 14 günlük ücretsiz deneme sürümü) |
Bağlantı kurmanın iki yolu vardır:
- Anahtar ile bağlantı — Zapier ve Make için geçerlidir. Kullanıcı uygulama içinden bir CRM seçip anahtarı kopyalar; platform ise web kancasını POST /crm/key/hooks ile abone yapar. Bu sayfada bu yöntem açıklanmaktadır.
- URL ile bağlantı — kendi sunucun için geçerlidir. Kullanıcı uygulama içinden Başka sistem (kendi URL adresin) seçeneğini belirler ve URL adresini buraya girer. Herhangi bir anahtar veya uç nokta gerekmez; uygulama imzalama gizli anahtarını gösterir.
| Yöntem | Uç nokta | Amaç |
|---|---|---|
| GET | /crm/key/me | Anahtarı doğrula ve bağlantı adını döndür |
| POST | /crm/key/hooks | Web kancası URL adresine abone ol |
| DELETE | /crm/key/hooks/{id} | Web kancası aboneliğini iptal et |
| GET | /crm/key/sample | Örnek bir proje kaydı al |
Kimlik doğrulama
Her istek, bağlantı anahtarını X-Api-Key üst bilgisinde taşır. Her anahtar, tek bir Home Planner hesabındaki tek bir CRM bağlantısına aittir. Anahtarı asla bir URL adresine ekleme.
X-Api-Key: hp_live_<accountId>_<connectionId>_<version>_<signature>Kullanıcı anahtarı Home Planner uygulamasından alır:
- Ayarlar ekranını aç ve projelerin nereye gönderileceğini seç.
- Bağlantı ekle düğmesine dokunup HubSpot, Pipedrive, Bitrix24, Salesforce veya Google Sheets platformlarından birini seç.
- Anahtarı kopyala seçeneğine dokun.
Kullanıcı Yeni anahtar düğmesine dokunduğunda veya bağlantıyı sildiğinde anahtar çalışmayı durdurur. Eksik, geçersiz veya değiştirilmiş bir anahtarla yapılan tüm istekler, {"code": "crm_key_invalid"} yanıtıyla birlikte 401 kodunu döndürür (DELETE yöntemi istisnadır, aşağıya bak).
GET /crm/key/me
Anahtarın ait olduğu bağlantıyı döndürür. Zapier bunu yeni bir bağlantıyı test etmek ve adlandırmak için çağırır.
curl https://icandesignapp.com/crm/key/me \
-H 'X-Api-Key: hp_live_…'Yanıt 200:
{
"connectionId": "65f0c3a2e4b0a1b2c3d4e5f7",
"name": "HubSpot deals",
"system": "hubspot"
}| Alan | Tür | Açıklama |
|---|---|---|
| connectionId | string | Bağlantı kimliği |
| ad | string | Uygulamadaki bağlantı adı, en fazla 24 karakter |
| system | string | hubspot, pipedrive, bitrix24, salesforce veya sheets |
Hatalar: 401 crm_key_invalid. Diğer hatalar için aşağıdaki Hatalar bölümüne bak.
POST /crm/key/hooks
Bu bağlantı üzerinden gönderilen her projeyi alan web kancası URL adresini ayarlar. Zapier bunu bir Zap etkinleştirildiğinde çağırır.
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/"}'Yanıt 201:
{
"id": "3f2b9c0d1e4a5b6c7d8e9f01"
}id değerini sakla: aboneliği sonlandırmak için buna ihtiyacın olacak.
- Bağlantı başına tek abonelik: yeni bir abonelik önceki URL adresinin yerine geçer.
- URL adresi https:// ile başlamalı, en fazla 2048 karakter uzunluğunda olmalı ve kullanıcı adı ya da şifre içermemelidir.
- Özel veya yerel ağları gösteren URL adresleri (bunlara yönlendirilen ana bilgisayar adları dahil) reddedilir: localhost, 127.*, 10.*, 172.16–31.*, 192.168.* ve 169.254.*.
| Durum | kod | Anlamı |
|---|---|---|
| 401 | crm_key_invalid | Eksik, geçersiz veya değiştirilmiş anahtar |
| 422 | crm_url_invalid | https:// URL adresi değil veya 2048 karakterden uzun |
| 422 | crm_url_credentials | URL adresi kullanıcı adı veya şifre içeriyor |
| 422 | crm_url_forbidden | URL adresi özel veya yerel bir ağı gösteriyor |
Diğer hatalar için aşağıdaki Hatalar bölümüne bak.
DELETE /crm/key/hooks/{id}
Bu id değerine sahip aboneliği kaldırır. Zapier bunu bir Zap kapatıldığında veya silindiğinde çağırır.
curl -X DELETE https://icandesignapp.com/crm/key/hooks/3f2b9c0d1e4a5b6c7d8e9f01 \
-H 'X-Api-Key: hp_live_…'Gövdesiz 204 yanıtı döner. Kimlik mevcut abonelikle eşleşmediğinde, anahtar değiştirildiğinde veya bağlantı silindiğinde de yanıt 204 olur. Her durumda da kaldırılacak bir şey kalmamıştır.
Hatalar: Eksik veya hiçbir zaman geçerli olmamış bir anahtar için 401 crm_key_invalid. Diğer hatalar için aşağıdaki Hatalar bölümüne bak.
GET /crm/key/sample
Gerçek bir iletimle aynı biçimde olan tek bir örnek proje kaydı içeren bir dizi döndürür. Zapier, kullanıcının bu alanları CRM alanlarıyla eşleştirebilmesi için onları gösterir.
curl https://icandesignapp.com/crm/key/sample \
-H 'X-Api-Key: hp_live_…'Yanıt 200: tek bir proje kaydı içeren bir dizi (aşağıda).
Hatalar: 401 crm_key_invalid. Diğer hatalar için aşağıdaki Hatalar bölümüne bak.
Web kancası iletimi
Kullanıcı uygulama içinde Paylaş → … sistemine gönder adımlarını takip ettiğinde Home Planner projeyi abone olunan URL adresine gönderir.
| Bölüm | Değer |
|---|---|
| Yöntem | POST |
| Content-Type | application/json |
| Gövde | Bir proje kaydı |
| X-HomePlanner-Delivery | İletim kimliği. Yeniden denemelerde aynı kalır: mükerrer kayıtları tespit etmek için bunu kullan. |
| X-HomePlanner-Signature | t=<saniye cinsinden unix zamanı>,v1=<küçük harf hex>; burada v1 = HMAC-SHA256(imzalama gizli anahtarı, t + "." + ham gövde) |
| Senin yanıtın | Home Planner'ın yaptığı işlem |
|---|---|
| 15 saniye içinde dönen herhangi bir 2xx yanıtı | İletildi |
| 15 saniye içinde yanıt alınamaması, 5xx, 408 veya 429 | 1 dakika, 10 dakika ve 1 saat sonra yeniden denenir. Proje ilk denemeden 2 saat sonra hâlâ iletilemediyse yeniden deneme durdurulur ve bağlantı uygulamada Hata olarak işaretlenir. |
| 410 Gone | Anahtar ile bağlantı: aboneliği kaldırır; tekrar abone olmak için Zap'i yeniden aç. URL ile bağlantı: diğer tüm 4xx yanıtlarıyla aynıdır |
| Diğer tüm 4xx yanıtları, yönlendirme veya sertifika hatası | Yeniden denenmez; uygulama bağlantıyı Hata olarak işaretler |
Her iletim imzalanır. Uygulama, imzalama gizli anahtarını yalnızca URL ile bağlantıda gösterir. İmza doğrulama adımları için Projeler Home Planner'dan CRM sistemine nasıl gönderilir sayfasına bakabilirsin.
Kullanıcının PRO++ aboneliği veya ücretsiz deneme süresi sona erdiğinde uygulama proje göndermeyi durdurur. Uç noktalar yanıt vermeye devam eder, bu nedenle Zap açık kalır ancak kullanıcı aboneliğini yenileyene kadar yeni proje alamaz.
Proje kaydı
Her iletim ve örnek uç noktası bu biçimi kullanır. Fiyatlar ve toplamlar uygulamadaki proje maliyet özetiyle eşleşir. Zapier'da bu kayıtta ayrıca bir id alanı da yer alır: bu alan client_reference_id değerinin bir kopyasıdır ve Gönderim ID olarak gösterilir.
{
"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"
}| Alan | Tür | Açıklama |
|---|---|---|
| client_reference_id | string | Bu gönderimin benzersiz kimliği |
| planNumber | string | Proje kimliği |
| planName | string | Proje adı |
| revisionUrl | string | Projeye giden herkese açık bağlantı |
| revisionNumber | string | Proje revizyonu |
| oluşturuldu, güncellendi | string, ISO 8601 | Projenin oluşturulduğu ve son kaydedildiği zaman |
| rooms[] | array | roomNumber, roomName, roomType, area (m²), height, width, depth (m), items |
| rooms[].items[] | array | itemNumber (Stok Kodu), name, quantity, price, currency, total, price_source, source, imageURL, note (kullanıcının ürün hakkındaki notu veya null), area (malzemeler için m²), components[] (ürünün parçaları: quantity değerinin ürünün tüm birimlerinin toplam sayısı olduğu aynı alanlar ve ek olarak birim başına sayıyı belirten quantityPerItem; örnek veri quantityPerItem alanını içermez) |
| price_source | string | company (şirket kataloğundaki fiyat) veya estimate (Home Planner maliyet özeti) |
| source | string | company (şirket kataloğundaki ürün) veya homeplanner (Home Planner kataloğu) |
| totals | object | items: üst düzey kalemlerin sayısı (parçalar dahil edilmez); sum: parçalar dahil toplam maliyet özeti; currency: para birimi kodu |
| pdfUrl | string veya null | Kat planı PDF dosyasına giden bağlantı; dosya 7 gün boyunca kullanılabilir |
| productsText | string | Düz metin olarak tam maliyet özeti |
| warning | string veya null | Örneğin: "Stok kodu olmayan 2 ürün bir Home Planner koduyla gönderildi" |
| entegrasyon | string | Her zaman "custom" |
Hız sınırları
| Kapsam | Sınır |
|---|---|
| Tek bir bağlantı anahtarı | Dakikada 30 istek, günde 500 istek |
| Geçersiz anahtarla yapılan istekler, IP adresi başına | Dakikada 300 istek, günde 5000 istek |
Bir sınır aşıldığında API, {"code": "crm_throttled"} yanıtıyla birlikte 429 kodunu döndürür.
Hatalar
Her hata, bir code alanı içeren JSON biçimindedir; örneğin {"code": "crm_key_invalid"}.
| Durum | kod | Anlamı |
|---|---|---|
| 401 | crm_key_invalid | Eksik, geçersiz veya değiştirilmiş anahtar |
| 422 | crm_url_invalid, crm_url_credentials, crm_url_forbidden | Web kancası URL adresi reddedildi |
| 429 | crm_throttled | Hız sınırına ulaşıldı |
| 503 | crm_unavailable | Geçici sunucu sorunu; daha sonra tekrar dene |
Destek
API ile ilgili soruların için: [email protected].
Ticari marka bildirimi. Zapier, Make, HubSpot, Pipedrive, Bitrix24, Salesforce ve Google Sheets kendi sahiplerinin ticari markalarıdır. Home Planner bu şirketlerden bağımsızdır; bu şirketler tarafından desteklenmemekte, sponsor olunmamakta veya bunlarla ortaklık yürütülmemektedir.
Kendi projende dene
Ücretsiz oda planlayıcı ve iç mekân tasarımı uygulaması


