Guida all'API CRM di Home Planner

Endpoint, autenticazione, invio tramite webhook e record di progetto dell'API CRM di Home Planner utilizzata da Zapier, Make e dal tuo server.

L'API CRM di Home Planner collega l'app Home Planner a Zapier, Make e al tuo server. Offre quattro endpoint, tutti autenticati tramite una chiave di connessione, e un webhook che invia ciascun progetto inoltrato dall'utente.
Questa pagina è rivolta a sviluppatori e piattaforme di integrazione. Per configurare l'invio dei progetti dall'app, consulta Come inviare i progetti da Home Planner al tuo CRM.
Panoramica
| Elemento | Valore |
|---|---|
| URL di base | https://icandesignapp.com (usa questo host: un reindirizzamento da homeplannerapp.com potrebbe eliminare il corpo della richiesta POST) |
| Formato | JSON su HTTPS |
| Autenticazione | Chiave di connessione nell'intestazione X-Api-Key |
| Invio | Webhook (REST hook): una richiesta POST per ciascun progetto inviato |
| Piano richiesto | PRO++ (o la prova gratuita di 14 giorni) |
Esistono due modalità di connessione:
- Connessione tramite chiave — per Zapier e Make. L'utente sceglie un CRM nell'app e copia la chiave; la piattaforma esegue l'iscrizione del proprio webhook tramite POST /crm/key/hooks. In questa pagina viene descritta questa modalità.
- Connessione tramite URL — per il tuo server. L'utente sceglie Altro sistema (il tuo URL) nell'app e vi inserisce l'URL. Non sono necessari né chiavi né endpoint e l'app mostra il segreto di firma.
| Metodo | Endpoint | Scopo |
|---|---|---|
| GET | /crm/key/me | Convalida la chiave e restituisce il nome della connessione |
| POST | /crm/key/hooks | Iscrivi un URL webhook |
| DELETE | /crm/key/hooks/{id} | Annulla l'iscrizione del webhook |
| GET | /crm/key/sample | Ottieni un record di progetto di esempio |
Autenticazione
Ogni richiesta contiene la chiave di connessione nell'intestazione X-Api-Key. Ciascuna chiave appartiene a una singola connessione CRM all'interno di un unico account Home Planner. Non inserire mai la chiave in un URL.
X-Api-Key: hp_live_<accountId>_<connectionId>_<version>_<signature>L'utente ottiene la chiave all'interno dell'app Home Planner:
- Apri Impostazioni e scegli dove inviare i progetti.
- Seleziona Aggiungi connessione e scegli HubSpot, Pipedrive, Bitrix24, Salesforce o Google Sheets.
- Seleziona Copia chiave.
Una chiave smette di funzionare quando l'utente seleziona Nuova chiave o elimina la connessione. Qualsiasi richiesta con una chiave mancante, non valida o sostituita restituisce l'errore 401 con {"code": "crm_key_invalid"} (l'unica eccezione è la richiesta DELETE, vedi sotto).
GET /crm/key/me
Restituisce la connessione a cui appartiene la chiave. Zapier la richiama per verificare e identificare una nuova connessione.
curl https://icandesignapp.com/crm/key/me \
-H 'X-Api-Key: hp_live_…'Risposta 200:
{
"connectionId": "65f0c3a2e4b0a1b2c3d4e5f7",
"name": "HubSpot deals",
"system": "hubspot"
}| Campo | Tipo | Descrizione |
|---|---|---|
| connectionId | stringa | ID della connessione |
| nome | stringa | Nome della connessione indicato nell'app, fino a 24 caratteri |
| sistema | stringa | hubspot, pipedrive, bitrix24, salesforce o sheets |
Errori: 401 crm_key_invalid. Per altri errori, consulta la sezione Errori di seguito.
POST /crm/key/hooks
Imposta l'URL webhook che riceve ogni progetto inviato tramite questa connessione. Zapier lo richiama quando uno Zap viene attivato.
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/"}'Risposta 201:
{
"id": "3f2b9c0d1e4a5b6c7d8e9f01"
}Conserva l'ID id: ti servirà per annullare l'iscrizione.
- È consentita una sola iscrizione per connessione: una nuova iscrizione sostituisce l'URL precedente.
- L'URL deve iniziare con https://, contenere al massimo 2048 caratteri e non deve includere nome utente o password.
- Gli URL che puntano a reti private o locali, compresi i nomi host che risolvono su di esse, vengono rifiutati: localhost, 127.*, 10.*, 172.16–31.*, 192.168.* e 169.254.*.
| Stato | codice | Significato |
|---|---|---|
| 401 | crm_key_invalid | Chiave mancante, non valida o sostituita |
| 422 | crm_url_invalid | L'URL non è nel formato https:// oppure supera i 2048 caratteri |
| 422 | crm_url_credentials | L'URL contiene un nome utente o una password |
| 422 | crm_url_forbidden | L'URL punta a una rete privata o locale |
Per altri errori, consulta la sezione Errori di seguito.
DELETE /crm/key/hooks/{id}
Rimuove l'iscrizione associata a questo id. Zapier lo richiama quando uno Zap viene disattivato o eliminato.
curl -X DELETE https://icandesignapp.com/crm/key/hooks/3f2b9c0d1e4a5b6c7d8e9f01 \
-H 'X-Api-Key: hp_live_…'Risposta 204 senza corpo. La risposta è 204 anche se l'ID non corrisponde all'iscrizione attuale, se la chiave è stata sostituita o se la connessione è stata eliminata. In tutti questi casi non c'è più nulla da rimuovere.
Errori: 401 crm_key_invalid se la chiave è mancante o non è mai stata valida. Per altri errori, consulta la sezione Errori di seguito.
GET /crm/key/sample
Restituisce un array contenente un record di progetto di esempio nello stesso formato di un invio reale. Zapier ne mostra i campi in modo che l'utente possa associarli ai campi del CRM.
curl https://icandesignapp.com/crm/key/sample \
-H 'X-Api-Key: hp_live_…'Risposta 200: un array con un record di progetto (vedi sotto).
Errori: 401 crm_key_invalid. Per altri errori, consulta la sezione Errori di seguito.
Invio tramite webhook
Quando l'utente seleziona Condividi → Invia a… nell'app, Home Planner invia il progetto all'URL iscritto tramite una richiesta POST.
| Parte | Valore |
|---|---|
| Metodo | POST |
| Content-Type | application/json |
| Corpo | Un record di progetto |
| X-HomePlanner-Delivery | ID dell'invio. Rimane invariato tra i vari tentativi: usalo per individuare i duplicati. |
| X-HomePlanner-Signature | t=<ora unix in secondi>,v1=<stringa esadecimale minuscola>, dove v1 = HMAC-SHA256(segreto di firma, t + "." + corpo grezzo) |
| La tua risposta | Azione eseguita da Home Planner |
|---|---|
| Un qualsiasi codice 2xx entro 15 secondi | Inviato |
| Nessuna risposta entro 15 secondi, 5xx, 408 o 429 | I tentativi vengono ripetuti dopo 1 minuto, 10 minuti e 1 ora. Se il progetto non è ancora stato inviato dopo 2 ore dal primo tentativo, i reinvii si interrompono e la connessione viene contrassegnata come Errore nell'app. |
| 410 Gone | Connessione tramite chiave: rimuove l'iscrizione; riattiva lo Zap per iscriverlo di nuovo. Connessione tramite URL: si comporta come un qualsiasi altro codice 4xx |
| Qualsiasi altro codice 4xx, un reindirizzamento o un errore di certificato | Nessun reinvio; l'app contrassegna la connessione come Errore |
Ogni invio viene firmato. L'app mostra il segreto di firma solo per la connessione tramite URL. Per la procedura di verifica della firma, consulta Come inviare i progetti da Home Planner al tuo CRM.
Quando l'abbonamento PRO++ o il periodo di prova gratuita dell'utente scade, l'app smette di inviare progetti. Gli endpoint continuano a rispondere, quindi lo Zap rimane attivo ma non riceverà nuovi progetti finché l'utente non rinnova l'abbonamento.
Record del progetto
Ciascun invio e l'endpoint di esempio utilizzano questo formato. I prezzi e i totali corrispondono al preventivo del progetto nell'app. In Zapier il record contiene anche il campo id: una copia di client_reference_id, visualizzata come ID invio.
{
"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"
}| Campo | Tipo | Descrizione |
|---|---|---|
| client_reference_id | stringa | ID univoco di questo invio |
| numeroPlan | stringa | ID del progetto |
| nomePlan | stringa | Nome del progetto |
| revisionUrl | stringa | Link pubblico al progetto |
| numeroRevisione | stringa | Revisione del progetto |
| creato, aggiornato | stringa, ISO 8601 | Data e ora in cui il progetto è stato creato e salvato per l'ultima volta |
| rooms[] | array | numeroStanza, nomeStanza, tipoStanza, area (m²), altezza, larghezza, profondità (m), elementi |
| rooms[].items[] | array | itemNumber (SKU), name, quantity, price, currency, total, price_source, source, imageURL, note (la nota dell'utente sull'articolo, oppure null), area (m², per i materiali), components[] (parti dell'articolo: contengono gli stessi campi, dove quantity indica la quantità totale per tutte le unità dell'articolo, a cui si aggiunge quantityPerItem, ovvero la quantità per singola unità; nel campione quantityPerItem viene omesso) |
| price_source | stringa | company (prezzo dal catalogo aziendale) o estimate (preventivo di Home Planner) |
| origine | stringa | company (prodotto dal catalogo aziendale) o homeplanner (catalogo di Home Planner) |
| totali | oggetto | items: numero di articoli principali (componenti esclusi); sum: totale del preventivo, componenti inclusi; currency: codice della valuta |
| pdfUrl | stringa o null | Link al PDF della planimetria; il file rimane disponibile per 7 giorni |
| productsText | stringa | L'intero preventivo in formato testo semplice |
| avviso | stringa o null | Ad esempio: "2 articoli senza SKU sono stati inviati con un codice Home Planner" |
| integrazione | stringa | Sempre "custom" |
Limiti di frequenza
| Ambito | Limite |
|---|---|
| Una chiave di connessione | 30 richieste al minuto, 500 al giorno |
| Richieste con chiave non valida, per indirizzo IP | 300 al minuto, 5000 al giorno |
Quando si supera un limite, l'API restituisce il codice 429 con {"code": "crm_throttled"}.
Errori
Ogni errore è restituito in formato JSON con il campo code, ad esempio {"code": "crm_key_invalid"}.
| Stato | codice | Significato |
|---|---|---|
| 401 | crm_key_invalid | Chiave mancante, non valida o sostituita |
| 422 | crm_url_invalid, crm_url_credentials, crm_url_forbidden | L'URL webhook è stato rifiutato |
| 429 | crm_throttled | Limite di frequenza raggiunto |
| 503 | crm_unavailable | Problema temporaneo del server; riprova più tardi |
Supporto
Domande sull'API: [email protected].
Note sui marchi. Zapier, Make, HubSpot, Pipedrive, Bitrix24, Salesforce e Google Sheets sono marchi registrati dei rispettivi proprietari. Home Planner è indipendente da queste società e non è da esse sponsorizzata, approvata o ad esse affiliata.
Provalo nel tuo progetto
App gratuita per la progettazione di stanze e di interni


