Home Planner
Terug naar HelpcentrumHandleidingen

Home Planner CRM API-referentie

Home Planner
Home PlannerApp-team · October 28, 2026

Eindpunten, authenticatie, webhook-aflevering en het projectrecord van de Home Planner CRM API die wordt gebruikt door Zapier, Make en je eigen server.

Home Planner-app verstuurt een kamerontwerp via Zapier naar HubSpot, Salesforce, Google Sheets en Pipedrive

De Home Planner CRM API verbindt de Home Planner-app met Zapier, Make en je eigen server. De API heeft vier eindpunten, die allemaal worden geauthenticeerd met een verbindingssleutel, en één webhook die elk project aflevert dat de gebruiker verstuurt.

Deze pagina is bedoeld voor ontwikkelaars en integratieplatforms. Raadpleeg Projecten versturen vanuit Home Planner naar je CRM om het versturen van projecten in de app in te stellen.

Overzicht

OnderdeelWaarde
Basis-URLhttps://icandesignapp.com (gebruik deze host: bij een omleiding vanaf homeplannerapp.com kan een POST-body verloren gaan)
IndelingJSON via HTTPS
AuthenticatieVerbindingssleutel in de header X-Api-Key
AfleveringWebhook (REST hook): één POST per verzonden project
Vereist abonnementPRO++ (of de gratis proefperiode van 14 dagen)

Er zijn twee manieren om verbinding te maken:

  1. Sleutelverbinding — voor Zapier en Make. De gebruiker kiest een CRM in de app en kopieert de sleutel; het platform abonneert zijn webhook via POST /crm/key/hooks. Deze pagina beschrijft deze methode.
  2. URL-verbinding — voor je eigen server. De gebruiker kiest Ander systeem (je URL) in de app en voert daar de URL in. Er zijn geen sleutel en geen eindpunten nodig, en de app toont het ondertekeningsgeheim.
MethodeEindpuntDoel
GET/crm/key/meDe sleutel valideren en de verbindingsnaam retourneren
POST/crm/key/hooksAbonneren op een webhook-URL
DELETE/crm/key/hooks/{id}Het abonnement op de webhook opzeggen
GET/crm/key/sampleEen voorbeeld van een projectrecord ophalen

Authenticatie

Elk verzoek bevat de verbindingssleutel in de header X-Api-Key. Elke sleutel hoort bij één CRM-verbinding in één Home Planner-account. Zet de sleutel nooit in een URL.

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

De gebruiker haalt de sleutel op in de Home Planner-app:

  1. Open Instellingen en kies waar je projecten naartoe wilt sturen.
  2. Selecteer Verbinding toevoegen en kies HubSpot, Pipedrive, Bitrix24, Salesforce of Google Sheets.
  3. Selecteer Sleutel kopiëren.

Een sleutel werkt niet meer zodra de gebruiker Nieuwe sleutel selecteert of de verbinding verwijdert. Elk verzoek met een ontbrekende, ongeldige of vervangende sleutel retourneert 401 met {"code": "crm_key_invalid"} (DELETE is de uitzondering, zie hieronder).

GET /crm/key/me

Retourneert de verbinding waar de sleutel bij hoort. Zapier aanroept dit om een nieuwe verbinding te testen en een label te geven.

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

Respons 200:

jsonjson
{
  "connectionId": "65f0c3a2e4b0a1b2c3d4e5f7",
  "name": "HubSpot deals",
  "system": "hubspot"
}
VeldTypeBeschrijving
connectionIdstringVerbindings-ID
namestringVerbindingsnaam uit de app, maximaal 24 tekens
systemstringhubspot, pipedrive, bitrix24, salesforce of sheets

Fouten: 401 crm_key_invalid. Zie Fouten hieronder voor overige fouten.

POST /crm/key/hooks

Stelt de webhook-URL in die elk project ontvangt dat via deze verbinding wordt verzonden. Zapier aanroept dit wanneer een Zap wordt ingeschakeld.

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

Respons 201:

jsonjson
{
  "id": "3f2b9c0d1e4a5b6c7d8e9f01"
}

Bewaar de id: je hebt deze nodig om het abonnement op te zeggen.

  • Eén abonnement per verbinding: een nieuw abonnement vervangt de vorige URL.
  • De URL moet beginnen met https://, mag maximaal 2048 tekens lang zijn en mag geen gebruikersnaam of wachtwoord bevatten.
  • URL's die naar particuliere of lokale netwerken verwijzen, inclusief hostnamen die daartoe leiden, worden geweigerd: localhost, 127.*, 10.*, 172.16–31.*, 192.168.* en 169.254.*.
StatuscodeBetekenis
401crm_key_invalidOntbrekende, ongeldige of vervangen sleutel
422crm_url_invalidGeen https://-URL, of langer dan 2048 tekens
422crm_url_credentialsDe URL bevat een gebruikersnaam of wachtwoord
422crm_url_forbiddenDe URL verwijst naar een particulier of lokaal netwerk

Zie Fouten hieronder voor overige fouten.

DELETE /crm/key/hooks/{id}

Verwijdert het abonnement met deze id. Zapier aanroept dit wanneer een Zap wordt uitgeschakeld of verwijderd.

bashbash
curl -X DELETE https://icandesignapp.com/crm/key/hooks/3f2b9c0d1e4a5b6c7d8e9f01 \
  -H 'X-Api-Key: hp_live_…'

Respons 204 zonder body. De respons is ook 204 als de ID niet overeenkomt met het huidige abonnement, de sleutel is vervanging of de verbinding is verwijderd. In al deze gevallen valt er niets meer te verwijderen.

Fouten: 401 crm_key_invalid bij een ontbrekende sleutel of een sleutel die nooit geldig is geweest. Zie Fouten hieronder voor overige fouten.

GET /crm/key/sample

Retourneert een array met één voorbeeld van een projectrecord in dezelfde indeling als een echte aflevering. Zapier toont de velden ervan, zodat de gebruiker ze kan koppelen aan CRM-velden.

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

Respons 200: een array met één projectrecord (zie hieronder).

Fouten: 401 crm_key_invalid. Zie Fouten hieronder voor overige fouten.

Webhook-aflevering

Wanneer de gebruiker in de app Delen → Verzenden naar … selecteert, post Home Planner het project naar de aangemelde URL.

OnderdeelWaarde
MethodePOST
Content-Typeapplication/json
BodyÉén projectrecord
X-HomePlanner-DeliveryAfleverings-ID. Deze blijft gelijk bij nieuwe pogingen: gebruik deze om dubbele items te detecteren.
X-HomePlanner-Signaturet=<unix-tijd in seconden>,v1=<kleine letters hex>, waarbij v1 = HMAC-SHA256(ondertekeningsgeheim, t + "." + ruwe body)
Je responsWat Home Planner doet
Elke 2xx binnen 15 secondenAfgeleverd
Geen respons binnen 15 seconden, 5xx, 408 of 429Nieuwe pogingen na 1 minuut, 10 minuten en 1 uur. Als het project 2 uur na de eerste poging nog steeds niet is afgeleverd, worden de pogingen gestopt en krijgt de verbinding in de app de status Fout.
410 GoneSleutelverbinding: verwijdert het abonnement; schakel de Zap opnieuw in om je weer te abonneren. URL-verbinding: hetzelfde als elke andere 4xx
Elke andere 4xx, een omleiding of een certificaatfoutGeen nieuwe poging; de app geeft de verbinding de status Fout

Elke aflevering wordt ondertekend. De app toont het ondertekeningsgeheim alleen bij een URL-verbinding. Raadpleeg Projecten versturen vanuit Home Planner naar je CRM voor de stappen om de handtekening te verifiëren.

Wanneer het PRO++-abonnement of de gratis proefperiode van de gebruiker afloopt, stopt de app met het versturen van projecten. De eindpunten blijven reageren, waardoor de Zap ingeschakeld blijft, maar er worden geen nieuwe projecten ontvangen totdat de gebruiker verlengt.

Projectrecord

Elke aflevering en het voorbeeld-eindpunt gebruiken deze indeling. Prijzen en totalen komen overeen met de projectofferte in de app. In Zapier bevat de record ook het veld id: een kopie van client_reference_id, getoond als Verzending-ID.

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"
}
VeldTypeBeschrijving
client_reference_idstringUnieke ID van deze verzending
planNumberstringProject-ID
planNamestringProjectnaam
revisionUrlstringOpenbare link naar het project
revisionNumberstringProjectrevisie
created, updatedstring, ISO 8601Wanneer het project is gemaakt en voor het laatst is opgeslagen
rooms[]arrayroomNumber, roomName, roomType, area (m²), height, width, depth (m), items
rooms[].items[]arrayitemNumber (SKU), name, quantity, price, currency, total, price_source, source, imageURL, note (de opmerking van de gebruiker bij het item, of null), area (m², voor materialen), components[] (onderdelen van het item: dezelfde velden, waarbij quantity het aantal voor alle eenheden van het item is, plus quantityPerItem, het aantal per eenheid; in het voorbeeld is quantityPerItem weggelaten)
price_sourcestringcompany (prijs uit de bedrijfscatalogus) of estimate (schatting van Home Planner)
sourcestringcompany (product uit de bedrijfscatalogus) of homeplanner (Home Planner-catalogus)
totalsobjectitems: aantal regelitems op het hoogste niveau (onderdelen niet meegeteld); sum: totaal van de offerte, inclusief onderdelen; currency: valutacode
pdfUrlstring of nullLink naar de pdf van de plattegrond; het bestand blijft 7 dagen beschikbaar
productsTextstringDe volledige offerte als platte tekst
warningstring of nullBijvoorbeeld: "2 item(s) zonder SKU zijn verzonden met een Home Planner-code"
integratiestringAltijd "custom"

Snelheidslimieten

BereikLimiet
Één verbindingssleutel30 verzoeken per minuut, 500 per dag
Verzoeken met een ongeldige sleutel, per IP-adres300 per minuut, 5000 per dag

Wanneer een limiet wordt overschreden, retourneert de API 429 met {"code": "crm_throttled"}.

Fouten

Elke fout is JSON met het veld code, bijvoorbeeld {"code": "crm_key_invalid"}.

StatuscodeBetekenis
401crm_key_invalidOntbrekende, ongeldige of vervangen sleutel
422crm_url_invalid, crm_url_credentials, crm_url_forbiddenDe webhook-URL is geweigerd
429crm_throttledSnelheidslimiet bereikt
503crm niet beschikbaarTijdelijk serverprobleem; probeer het later opnieuw

Ondersteuning

Vragen over de API: [email protected].

Kennisgeving inzake handelsmerken. Zapier, Make, HubSpot, Pipedrive, Bitrix24, Salesforce en Google Sheets zijn handelsmerken van hun respectieve eigenaren. Home Planner is onafhankelijk van deze bedrijven en wordt niet door hen ondersteund, gesponsord of erbij aangesloten.

Home Planner

Probeer het uit in je eigen project

Gratis app voor plattegronden en interieurontwerp