Home Planner CRM API-referentie

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

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
| Onderdeel | Waarde |
|---|---|
| Basis-URL | https://icandesignapp.com (gebruik deze host: bij een omleiding vanaf homeplannerapp.com kan een POST-body verloren gaan) |
| Indeling | JSON via HTTPS |
| Authenticatie | Verbindingssleutel in de header X-Api-Key |
| Aflevering | Webhook (REST hook): één POST per verzonden project |
| Vereist abonnement | PRO++ (of de gratis proefperiode van 14 dagen) |
Er zijn twee manieren om verbinding te maken:
- 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.
- 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.
| Methode | Eindpunt | Doel |
|---|---|---|
| GET | /crm/key/me | De sleutel valideren en de verbindingsnaam retourneren |
| POST | /crm/key/hooks | Abonneren op een webhook-URL |
| DELETE | /crm/key/hooks/{id} | Het abonnement op de webhook opzeggen |
| GET | /crm/key/sample | Een 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.
X-Api-Key: hp_live_<accountId>_<connectionId>_<version>_<signature>De gebruiker haalt de sleutel op in de Home Planner-app:
- Open Instellingen en kies waar je projecten naartoe wilt sturen.
- Selecteer Verbinding toevoegen en kies HubSpot, Pipedrive, Bitrix24, Salesforce of Google Sheets.
- 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.
curl https://icandesignapp.com/crm/key/me \
-H 'X-Api-Key: hp_live_…'Respons 200:
{
"connectionId": "65f0c3a2e4b0a1b2c3d4e5f7",
"name": "HubSpot deals",
"system": "hubspot"
}| Veld | Type | Beschrijving |
|---|---|---|
| connectionId | string | Verbindings-ID |
| name | string | Verbindingsnaam uit de app, maximaal 24 tekens |
| system | string | hubspot, 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.
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:
{
"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.*.
| Status | code | Betekenis |
|---|---|---|
| 401 | crm_key_invalid | Ontbrekende, ongeldige of vervangen sleutel |
| 422 | crm_url_invalid | Geen https://-URL, of langer dan 2048 tekens |
| 422 | crm_url_credentials | De URL bevat een gebruikersnaam of wachtwoord |
| 422 | crm_url_forbidden | De 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.
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.
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.
| Onderdeel | Waarde |
|---|---|
| Methode | POST |
| Content-Type | application/json |
| Body | Één projectrecord |
| X-HomePlanner-Delivery | Afleverings-ID. Deze blijft gelijk bij nieuwe pogingen: gebruik deze om dubbele items te detecteren. |
| X-HomePlanner-Signature | t=<unix-tijd in seconden>,v1=<kleine letters hex>, waarbij v1 = HMAC-SHA256(ondertekeningsgeheim, t + "." + ruwe body) |
| Je respons | Wat Home Planner doet |
|---|---|
| Elke 2xx binnen 15 seconden | Afgeleverd |
| Geen respons binnen 15 seconden, 5xx, 408 of 429 | Nieuwe 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 Gone | Sleutelverbinding: 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 certificaatfout | Geen 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.
{
"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"
}| Veld | Type | Beschrijving |
|---|---|---|
| client_reference_id | string | Unieke ID van deze verzending |
| planNumber | string | Project-ID |
| planName | string | Projectnaam |
| revisionUrl | string | Openbare link naar het project |
| revisionNumber | string | Projectrevisie |
| created, updated | string, ISO 8601 | Wanneer het project is gemaakt en voor het laatst is opgeslagen |
| rooms[] | array | roomNumber, roomName, roomType, area (m²), height, width, depth (m), items |
| rooms[].items[] | array | itemNumber (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_source | string | company (prijs uit de bedrijfscatalogus) of estimate (schatting van Home Planner) |
| source | string | company (product uit de bedrijfscatalogus) of homeplanner (Home Planner-catalogus) |
| totals | object | items: aantal regelitems op het hoogste niveau (onderdelen niet meegeteld); sum: totaal van de offerte, inclusief onderdelen; currency: valutacode |
| pdfUrl | string of null | Link naar de pdf van de plattegrond; het bestand blijft 7 dagen beschikbaar |
| productsText | string | De volledige offerte als platte tekst |
| warning | string of null | Bijvoorbeeld: "2 item(s) zonder SKU zijn verzonden met een Home Planner-code" |
| integratie | string | Altijd "custom" |
Snelheidslimieten
| Bereik | Limiet |
|---|---|
| Één verbindingssleutel | 30 verzoeken per minuut, 500 per dag |
| Verzoeken met een ongeldige sleutel, per IP-adres | 300 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"}.
| Status | code | Betekenis |
|---|---|---|
| 401 | crm_key_invalid | Ontbrekende, ongeldige of vervangen sleutel |
| 422 | crm_url_invalid, crm_url_credentials, crm_url_forbidden | De webhook-URL is geweigerd |
| 429 | crm_throttled | Snelheidslimiet bereikt |
| 503 | crm niet beschikbaar | Tijdelijk 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.
Probeer het uit in je eigen project
Gratis app voor plattegronden en interieurontwerp


