Home Planner
Torna al Centro assistenzaGuide pratiche

Guida all'API CRM di Home Planner

Home Planner
Home PlannerTeam dell'app · October 28, 2026

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

L'app Home Planner invia un progetto di design della stanza tramite Zapier a HubSpot, Salesforce, Google Sheets e Pipedrive

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

ElementoValore
URL di basehttps://icandesignapp.com (usa questo host: un reindirizzamento da homeplannerapp.com potrebbe eliminare il corpo della richiesta POST)
FormatoJSON su HTTPS
AutenticazioneChiave di connessione nell'intestazione X-Api-Key
InvioWebhook (REST hook): una richiesta POST per ciascun progetto inviato
Piano richiestoPRO++ (o la prova gratuita di 14 giorni)

Esistono due modalità di connessione:

  1. 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à.
  2. 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.
MetodoEndpointScopo
GET/crm/key/meConvalida la chiave e restituisce il nome della connessione
POST/crm/key/hooksIscrivi un URL webhook
DELETE/crm/key/hooks/{id}Annulla l'iscrizione del webhook
GET/crm/key/sampleOttieni 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.

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

L'utente ottiene la chiave all'interno dell'app Home Planner:

  1. Apri Impostazioni e scegli dove inviare i progetti.
  2. Seleziona Aggiungi connessione e scegli HubSpot, Pipedrive, Bitrix24, Salesforce o Google Sheets.
  3. 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.

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

Risposta 200:

jsonjson
{
  "connectionId": "65f0c3a2e4b0a1b2c3d4e5f7",
  "name": "HubSpot deals",
  "system": "hubspot"
}
CampoTipoDescrizione
connectionIdstringaID della connessione
nomestringaNome della connessione indicato nell'app, fino a 24 caratteri
sistemastringahubspot, 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.

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

Risposta 201:

jsonjson
{
  "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.*.
StatocodiceSignificato
401crm_key_invalidChiave mancante, non valida o sostituita
422crm_url_invalidL'URL non è nel formato https:// oppure supera i 2048 caratteri
422crm_url_credentialsL'URL contiene un nome utente o una password
422crm_url_forbiddenL'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.

bashbash
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.

bashbash
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.

ParteValore
MetodoPOST
Content-Typeapplication/json
CorpoUn record di progetto
X-HomePlanner-DeliveryID dell'invio. Rimane invariato tra i vari tentativi: usalo per individuare i duplicati.
X-HomePlanner-Signaturet=<ora unix in secondi>,v1=<stringa esadecimale minuscola>, dove v1 = HMAC-SHA256(segreto di firma, t + "." + corpo grezzo)
La tua rispostaAzione eseguita da Home Planner
Un qualsiasi codice 2xx entro 15 secondiInviato
Nessuna risposta entro 15 secondi, 5xx, 408 o 429I 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 GoneConnessione 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 certificatoNessun 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.

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"
}
CampoTipoDescrizione
client_reference_idstringaID univoco di questo invio
numeroPlanstringaID del progetto
nomePlanstringaNome del progetto
revisionUrlstringaLink pubblico al progetto
numeroRevisionestringaRevisione del progetto
creato, aggiornatostringa, ISO 8601Data e ora in cui il progetto è stato creato e salvato per l'ultima volta
rooms[]arraynumeroStanza, nomeStanza, tipoStanza, area (m²), altezza, larghezza, profondità (m), elementi
rooms[].items[]arrayitemNumber (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_sourcestringacompany (prezzo dal catalogo aziendale) o estimate (preventivo di Home Planner)
originestringacompany (prodotto dal catalogo aziendale) o homeplanner (catalogo di Home Planner)
totalioggettoitems: numero di articoli principali (componenti esclusi); sum: totale del preventivo, componenti inclusi; currency: codice della valuta
pdfUrlstringa o nullLink al PDF della planimetria; il file rimane disponibile per 7 giorni
productsTextstringaL'intero preventivo in formato testo semplice
avvisostringa o nullAd esempio: "2 articoli senza SKU sono stati inviati con un codice Home Planner"
integrazionestringaSempre "custom"

Limiti di frequenza

AmbitoLimite
Una chiave di connessione30 richieste al minuto, 500 al giorno
Richieste con chiave non valida, per indirizzo IP300 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"}.

StatocodiceSignificato
401crm_key_invalidChiave mancante, non valida o sostituita
422crm_url_invalid, crm_url_credentials, crm_url_forbiddenL'URL webhook è stato rifiutato
429crm_throttledLimite di frequenza raggiunto
503crm_unavailableProblema 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.

Home Planner

Provalo nel tuo progetto

App gratuita per la progettazione di stanze e di interni