Dokumentacja API Home Planner CRM

Punkty końcowe, uwierzytelnianie, doręczanie webhooków i rekord projektu w API Home Planner CRM używanym przez Zapier, Make i własny serwer.

API Home Planner CRM łączy aplikację Home Planner z usługami Zapier i Make oraz z własnym serwerem. Udostępnia cztery punkty końcowe – wszystkie uwierzytelniane kluczem połączenia – oraz jeden webhook, który przesyła każdy projekt wysłany przez użytkownika.
Ta strona jest przeznaczona dla programistów i twórców platform integracyjnych. Aby skonfigurować wysyłanie projektów w aplikacji, zobacz artykuł Jak wysyłać projekty z Home Planner do systemu CRM.
Przegląd
| Element | Wartość |
|---|---|
| Bazowy URL | https://icandesignapp.com (należy używać tego hosta: przekierowanie z homeplannerapp.com może odrzucić treść żądania POST) |
| Format | JSON przez HTTPS |
| Uwierzytelnianie | Klucz połączenia w nagłówku X-Api-Key |
| Dostarczanie | Webhook (REST hook): jedno żądanie POST na wysłany projekt |
| Wymagany plan | PRO++ (lub jego 14-dniowy bezpłatny okres próbny) |
Istnieją dwa sposoby połączenia:
- Połączenie za pomocą klucza — dla usług Zapier i Make. Użytkownik wybiera system CRM w aplikacji i kopiuje klucz; platforma subskrybuje swój webhook za pomocą metody POST /crm/key/hooks. Ta strona opisuje ten sposób.
- Połączenie za pomocą adresu URL — dla własnego serwera. Użytkownik wybiera opcję Inny system (Twój URL) w aplikacji i tam wpisuje adres URL. Klucz ani punkty końcowe nie są wymagane, a aplikacja wyświetla sekret podpisywania.
| Metoda | Punkt końcowy | Cel |
|---|---|---|
| GET | /crm/key/me | Weryfikacja klucza i zwrot nazwy połączenia |
| POST | /crm/key/hooks | Subskrypcja adresu URL webhooka |
| DELETE | /crm/key/hooks/{id} | Anulowanie subskrypcji webhooka |
| GET | /crm/key/sample | Pobranie przykładowego rekordu projektu |
Uwierzytelnianie
Każde żądanie zawiera klucz połączenia w nagłówku X-Api-Key. Każdy klucz należy do jednego połączenia CRM w ramach jednego konta Home Planner. Nigdy nie należy umieszczać klucza w adresie URL.
X-Api-Key: hp_live_<accountId>_<connectionId>_<version>_<signature>Klucz można uzyskać w aplikacji Home Planner:
- Otworzyć Ustawienia i wybrać miejsce wysyłania projektów.
- Wybrać Dodaj połączenie oraz wybrać HubSpot, Pipedrive, Bitrix24, Salesforce lub Google Sheets.
- Wybrać Kopiuj klucz.
Klucz przestaje działać, gdy użytkownik wybierze opcję Nowy klucz lub usunie połączenie. Każde żądanie z brakiem klucza, nieprawidłowym kluczem lub zastąpionym kluczem zwraca kod 401 z kodem błędu {"code": "crm_key_invalid"} (wyjątkiem jest metoda DELETE, zobacz poniżej).
GET /crm/key/me
Zwraca połączenie, do którego należy klucz. Usługa Zapier wywołuje tę metodę, aby przetestować nowe połączenie i nadać mu etykietę.
curl https://icandesignapp.com/crm/key/me \
-H 'X-Api-Key: hp_live_…'Odpowiedź 200:
{
"connectionId": "65f0c3a2e4b0a1b2c3d4e5f7",
"name": "HubSpot deals",
"system": "hubspot"
}| Pole | Typ | Opis |
|---|---|---|
| connectionId | ciąg znaków | Identyfikator połączenia |
| nazwa | ciąg znaków | Nazwa połączenia z aplikacji, do 24 znaków |
| system | ciąg znaków | hubspot, pipedrive, bitrix24, salesforce lub sheets |
Błędy: 401 crm_key_invalid. Inne błędy: zobacz sekcję Błędy poniżej.
POST /crm/key/hooks
Ustawia adres URL webhooka odbierający każdy projekt wysłany przez to połączenie. Usługa Zapier wywołuje tę metodę w momencie włączenia reguły 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/"}'Odpowiedź 201:
{
"id": "3f2b9c0d1e4a5b6c7d8e9f01"
}Zapisz identyfikator id: jest potrzebny do anulowania subskrypcji.
- Jedna subskrypcja na połączenie: nowa subskrypcja zastępuje poprzedni adres URL.
- Adres URL musi zaczynać się od https://, mieć maksymalnie 2048 znaków oraz nie może zawierać nazwy użytkownika ani hasła.
- Adresy URL wskazujące na sieci prywatne lub lokalne, w tym nazwy hostów wskazujące na nie, są odrzucane: localhost, 127.*, 10.*, 172.16–31.*, 192.168.* oraz 169.254.*.
| Status | kod | Znaczenie |
|---|---|---|
| 401 | crm_key_invalid | Brak klucza, nieprawidłowy klucz lub klucz zastąpiony |
| 422 | crm_url_invalid | Adres inny niż https:// lub dłuższy niż 2048 znaków |
| 422 | crm_url_credentials | Adres URL zawiera nazwę użytkownika lub hasło |
| 422 | crm_url_forbidden | Adres URL wskazuje na sieć prywatną lub lokalną |
Inne błędy: zobacz sekcję Błędy poniżej.
DELETE /crm/key/hooks/{id}
Usuwa subskrypcję o danym identyfikatorze id. Usługa Zapier wywołuje tę metodę po wyłączeniu lub usunięciu reguły Zap.
curl -X DELETE https://icandesignapp.com/crm/key/hooks/3f2b9c0d1e4a5b6c7d8e9f01 \
-H 'X-Api-Key: hp_live_…'Odpowiedź 204 bez treści. Odpowiedź ma również kod 204, jeśli identyfikator nie pasuje do aktualnej subskrypcji, klucz został zastąpiony lub połączenie zostało usunięte. W każdym z tych przypadków nie ma już nic do usunięcia.
Błędy: 401 crm_key_invalid w przypadku braku klucza lub klucza, który nigdy nie był prawidłowy. Inne błędy: zobacz sekcję Błędy poniżej.
GET /crm/key/sample
Zwraca tablicę z jednym przykładowym rekordem projektu w takim samym formacie, jak w przypadku rzeczywistego doręczenia. Usługa Zapier wyświetla jego pola, aby użytkownik mógł przypisać je do pól w systemie CRM.
curl https://icandesignapp.com/crm/key/sample \
-H 'X-Api-Key: hp_live_…'Odpowiedź 200: tablica z jednym rekordem projektu (poniżej).
Błędy: 401 crm_key_invalid. Inne błędy: zobacz sekcję Błędy poniżej.
Doręczanie przez webhook
Po wybraniu w aplikacji opcji Udostępnij → Wyślij do… Home Planner przesyła projekt pod zasubskrybowany adres URL.
| Część | Wartość |
|---|---|
| Metoda | POST |
| Content-Type | application/json |
| Treść | Jeden rekord projektu |
| X-HomePlanner-Delivery | Identyfikator doręczenia. Pozostaje taki sam przy ponownych próbach: służy do wykrywania duplikatów. |
| X-HomePlanner-Signature | t=<czas uniksowy w sekundach>,v1=<zapis szesnastkowy małymi literami>, gdzie v1 = HMAC-SHA256(sekret podpisywania, t + "." + surowa treść) |
| Twoja odpowiedź | Działanie aplikacji Home Planner |
|---|---|
| Dowolny kod 2xx w ciągu 15 sekund | Doręczono |
| Brak odpowiedzi w ciągu 15 sekund, kod 5xx, 408 lub 429 | Ponawia próbę po 1 minucie, 10 minutach i 1 godzinie. Jeśli po 2 godzinach od pierwszej próby projekt nadal nie zostanie doręczony, zaprzestaje ponawiania prób i oznacza połączenie w aplikacji jako Błąd. |
| 410 Gone | Połączenie za pomocą klucza: usuwa subskrypcję; należy włączyć regułę Zap ponownie, aby odnowić subskrypcję. Połączenie za pomocą adresu URL: tak samo jak przy każdym innym kodzie 4xx |
| Dowolny inny kod 4xx, przekierowanie lub błąd certyfikatu | Brak ponownych prób; aplikacja oznacza połączenie jako Błąd |
Każde doręczenie jest podpisane. Aplikacja wyświetla sekret podpisywania tylko w przypadku połączenia za pomocą adresu URL. Kroki weryfikacji podpisu znajdują się w artykule Jak wysyłać projekty z Home Planner do systemu CRM.
Gdy subskrypcja PRO++ lub bezpłatny okres próbny użytkownika dobiegnie końca, aplikacja przestaje wysyłać projekty. Punkty końcowe nadal odpowiadają, więc reguła Zap pozostaje włączona, ale nie otrzymuje nowych projektów, dopóki użytkownik nie odnowi subskrypcji.
Rekord projektu
Ten format stosowany jest przy każdym doręczeniu oraz w punkcie końcowym dla próbki. Ceny i sumy zgadzają się z kosztorysem projektu w aplikacji. W usłudze Zapier rekord ma również pole id: kopię pola client_reference_id, widoczną jako Identyfikator wysyłki.
{
"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"
}| Pole | Typ | Opis |
|---|---|---|
| client_reference_id | ciąg znaków | Unikalny identyfikator tej wysyłki |
| planNumber | ciąg znaków | Identyfikator projektu |
| planName | ciąg znaków | Nazwa projektu |
| revisionUrl | ciąg znaków | Publiczny link do projektu |
| revisionNumber | ciąg znaków | Wersja projektu |
| utworzone, zaktualizowane | ciąg znaków, ISO 8601 | Data utworzenia i ostatniego zapisu projektu |
| rooms[] | tablica | roomNumber, roomName, roomType, area (m²), height, width, depth (m), items |
| rooms[].items[] | tablica | itemNumber (SKU), name, quantity, price, currency, total, price_source, source, imageURL, note (notatka użytkownika dotycząca elementu lub wartość null), area (m², dla materiałów), components[] (części składowe elementu: te same pola, przy czym quantity to liczba dla wszystkich sztuk elementu, oraz dodatkowo quantityPerItem, czyli liczba przypadająca na sztukę; przykład pomija pole quantityPerItem) |
| price_source | ciąg znaków | company (cena z katalogu firmy) lub estimate (kosztorys Home Planner) |
| source | ciąg znaków | company (produkt z katalogu firmy) lub homeplanner (katalog Home Planner) |
| totals | obiekt | items: liczba pozycji najwyższego poziomu (bez uwzględnienia części składowych); sum: łączna kwota kosztorysu wraz z częściami składowymi; currency: kod waluty |
| pdfUrl | ciąg znaków lub null | Link do pliku PDF z rzutem kondygnacji; plik jest dostępny przez 7 dni |
| productsText | ciąg znaków | Pełny kosztorys w postaci czystego tekstu |
| ostrzeżenie | ciąg znaków lub null | Na przykład: "Liczba elementów bez SKU wysłanych z kodem Home Planner: 2" |
| integracja | ciąg znaków | Zawsze "custom" |
Limity żądań
| Zakres | Limit |
|---|---|
| Jeden klucz połączenia | 30 żądań na minutę, 500 dziennie |
| Żądania z nieprawidłowym kluczem na adres IP | 300 na minutę, 5000 dziennie |
Po przekroczeniu limitu interfejs API zwraca kod 429 z kodem błędu {"code": "crm_throttled"}.
Błędy
Każdy błąd jest obiektem JSON z polem code, na przykład {"code": "crm_key_invalid"}.
| Status | kod | Znaczenie |
|---|---|---|
| 401 | crm_key_invalid | Brak klucza, nieprawidłowy klucz lub klucz zastąpiony |
| 422 | crm_url_invalid, crm_url_credentials, crm_url_forbidden | Adres URL webhooka został odrzucony |
| 429 | crm_throttled | Osiągnięto limit żądań |
| 503 | crm_unavailable | Chwilowy problem z serwerem; należy spróbować ponownie później |
Pomoc techniczna
Pytania dotyczące interfejsu API: [email protected].
Informacja o znakach towarowych. Zapier, Make, HubSpot, Pipedrive, Bitrix24, Salesforce i Google Sheets są znakami towarowymi ich właścicieli. Home Planner jest niezależny od tych firm i nie jest przez nie wspierany, sponsorowany ani z nimi powiązany.
Wypróbować we własnym projekcie
Bezpłatna aplikacja do planowania pomieszczeń i aranżacji wnętrz


