CRM-API-Referenz von Home Planner

Endpunkte, Authentifizierung, Webhook-Übertragung und der Projektdatensatz der CRM-API von Home Planner für Zapier, Make und deinen eigenen Server.

Die CRM-API von Home Planner verbindet die Home-Planner-App mit Zapier, Make und deinem eigenen Server. Sie bietet vier Endpunkte, die alle mit einem Verbindungsschlüssel authentifiziert werden, sowie einen Webhook, der jedes vom Benutzer gesendete Projekt überträgt.
Diese Seite richtet sich an Entwickler und Integrationsplattformen. Wenn du das Senden von Projekten in der App einrichten möchtest, lies den Artikel So sendest du Projekte aus Home Planner an dein CRM.
Übersicht
| Eintrag | Wert |
|---|---|
| Basis-URL | https://icandesignapp.com (nutze diesen Host; bei einer Weiterleitung von homeplannerapp.com kann der POST-Body verloren gehen) |
| Format | JSON über HTTPS |
| Authentifizierung | Verbindungsschlüssel im Header „X-Api-Key“ |
| Übertragung | Webhook (REST-Hook): ein POST pro gesendetem Projekt |
| Erforderlicher Tarif | PRO++ (oder die kostenlose 14-Tage-Testversion) |
Es gibt zwei Verbindungsarten:
- Verbindung per Schlüssel – für Zapier und Make. Du wählst in der App ein CRM aus und kopierst den Schlüssel; die Plattform abonniert ihren Webhook über POST /crm/key/hooks. Diese Variante wird auf dieser Seite beschrieben.
- Verbindung per URL – für deinen eigenen Server. Du wählst in der App Anderes System (eigene URL) und gibst dort die URL ein. Es werden weder Schlüssel noch Endpunkte benötigt, und die App zeigt das Signaturgeheimnis an.
| Methode | Endpunkt | Zweck |
|---|---|---|
| GET | /crm/key/me | Schlüssel prüfen und den Verbindungsnamen zurückgeben |
| POST | /crm/key/hooks | Webhook-URL abonnieren |
| DELETE | /crm/key/hooks/{id} | Webhook-Abonnement kündigen |
| GET | /crm/key/sample | Beispiel-Projektdatensatz abrufen |
Authentifizierung
Jede Anfrage enthält den Verbindungsschlüssel im Header X-Api-Key. Jeder Schlüssel gehört zu genau einer CRM-Verbindung in einem einzelnen Home-Planner-Konto. Binde den Schlüssel niemals in eine URL ein.
X-Api-Key: hp_live_<accountId>_<connectionId>_<version>_<signature>Den Schlüssel erhältst du in der Home-Planner-App:
- Öffne die Einstellungen und wähle aus, wohin Projekte gesendet werden sollen.
- Wähle Verbindung hinzufügen und wähle HubSpot, Pipedrive, Bitrix24, Salesforce oder Google Sheets aus.
- Wähle Schlüssel kopieren.
Ein Schlüssel verliert seine Gültigkeit, sobald du Neuer Schlüssel wählst oder die Verbindung löschst. Jede Anfrage mit einem fehlenden, ungültigen oder ersetzten Schlüssel gibt 401 mit {"code": "crm_key_invalid"} zurück (DELETE bildet die Ausnahme, siehe unten).
GET /crm/key/me
Gibt die Verbindung zurück, zu der der Schlüssel gehört. Zapier ruft diesen Endpunkt auf, um eine neue Verbindung zu testen und zu benennen.
curl https://icandesignapp.com/crm/key/me \
-H 'X-Api-Key: hp_live_…'Antwort 200:
{
"connectionId": "65f0c3a2e4b0a1b2c3d4e5f7",
"name": "HubSpot deals",
"system": "hubspot"
}| Feld | Typ | Beschreibung |
|---|---|---|
| connectionId | String | Verbindungs-ID |
| Name | String | Verbindungsname aus der App, bis zu 24 Zeichen |
| System | String | hubspot, pipedrive, bitrix24, salesforce oder sheets |
Fehler: 401 crm_key_invalid. Weitere Fehler: siehe Abschnitt „Fehler“ unten.
POST /crm/key/hooks
Legt die Webhook-URL fest, die jedes über diese Verbindung gesendete Projekt empfängt. Zapier ruft diesen Endpunkt auf, wenn ein Zap aktiviert wird.
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/"}'Antwort 201:
{
"id": "3f2b9c0d1e4a5b6c7d8e9f01"
}Speichere die id: Du benötigst sie, um das Abonnement wieder zu kündigen.
- Ein Abonnement pro Verbindung: Ein neues Abonnement ersetzt die vorherige URL.
- Die URL muss mit https:// beginnen, darf höchstens 2048 Zeichen lang sein und darf weder Benutzernamen noch Passwort enthalten.
- URLs, die auf private oder lokale Netzwerke verweisen (einschließlich Hostnamen, die darauf auflösen), werden abgelehnt: localhost, 127.*, 10.*, 172.16–31.*, 192.168.* und 169.254.*.
| Status | Code | Bedeutung |
|---|---|---|
| 401 | crm_key_invalid | Fehlender, ungültiger oder ersetzter Schlüssel |
| 422 | crm_url_invalid | Keine https://-URL oder länger als 2048 Zeichen |
| 422 | crm_url_credentials | Die URL enthält einen Benutzernamen oder ein Passwort |
| 422 | crm_url_forbidden | Die URL verweist auf ein privates oder lokales Netzwerk |
Weitere Fehler: siehe Abschnitt „Fehler“ unten.
DELETE /crm/key/hooks/{id}
Entfernt das Abonnement mit dieser id. Zapier ruft diesen Endpunkt auf, wenn ein Zap deaktiviert oder gelöscht wird.
curl -X DELETE https://icandesignapp.com/crm/key/hooks/3f2b9c0d1e4a5b6c7d8e9f01 \
-H 'X-Api-Key: hp_live_…'Antwort 204 ohne Inhalt. Die Antwort lautet ebenfalls 204, wenn die ID nicht zum aktuellen Abonnement passt, der Schlüssel ersetzt wurde oder die Verbindung gelöscht wurde. In all diesen Fällen gibt es nichts mehr zu entfernen.
Fehler: 401 crm_key_invalid bei fehlendem Schlüssel oder einem Schlüssel, der nie gültig war. Weitere Fehler: siehe Abschnitt „Fehler“ unten.
GET /crm/key/sample
Gibt ein Array mit einem Beispiel-Projektdatensatz im selben Format wie bei einer echten Übertragung zurück. Zapier zeigt dessen Felder an, damit du sie den CRM-Feldern zuordnen kannst.
curl https://icandesignapp.com/crm/key/sample \
-H 'X-Api-Key: hp_live_…'Antwort 200: ein Array mit einem Projektdatensatz (siehe unten).
Fehler: 401 crm_key_invalid. Weitere Fehler: siehe Abschnitt „Fehler“ unten.
Webhook-Übertragung
Sobald du in der App Teilen → Senden an … wählst, überträgt Home Planner das Projekt per POST an die abonnierte URL.
| Teil | Wert |
|---|---|
| Methode | POST |
| Content-Type | application/json |
| Body | Ein Projektdatensatz |
| X-HomePlanner-Delivery | Übertragungs-ID. Sie bleibt bei erneuten Zustellversuchen unverändert: Verwende sie zur Erkennung von Duplikaten. |
| X-HomePlanner-Signature | t=<Unix-Zeit in Sekunden>,v1=<Hexadezimalwert in Kleinbuchstaben>, wobei v1 = HMAC-SHA256(Signaturgeheimnis, t + "." + Roh-Body) |
| Deine Antwort | Reaktion von Home Planner |
|---|---|
| Beliebiger 2xx-Code innerhalb von 15 Sekunden | Zugestellt |
| Keine Antwort innerhalb von 15 Sekunden, 5xx, 408 oder 429 | Erneute Zustellversuche nach 1 Minute, 10 Minuten und 1 Stunde. Wenn das Projekt 2 Stunden nach dem ersten Versuch noch immer nicht zugestellt werden konnte, werden keine weiteren Versuche unternommen und die Verbindung wird in der App als fehlerhaft markiert. |
| 410 Gone | Verbindung per Schlüssel: Das Abonnement wird entfernt; aktiviere den Zap erneut, um es wieder einzurichten. Verbindung per URL: verhält sich wie jeder andere 4xx-Fehler. |
| Jeder andere 4xx-Code, eine Weiterleitung oder ein Zertifikatsfehler | Kein erneuter Versuch; die App markiert die Verbindung als fehlerhaft |
Jede Übertragung ist signiert. Die App zeigt das Signaturgeheimnis nur bei einer Verbindung per URL an. Die Schritte zur Überprüfung der Signatur findest du unter So sendest du Projekte aus Home Planner an dein CRM.
Sobald das PRO++-Abonnement oder die Testversion abläuft, werden keine Projekte mehr gesendet. Die Endpunkte antworten weiterhin, sodass der Zap aktiv bleibt, jedoch keine neuen Projekte empfängt, bis das Abonnement verlängert wird.
Projektdatensatz
Jede Übertragung und der Beispiel-Endpunkt nutzen dieses Format. Preise und Gesamtsummen entsprechen dem Kostenvoranschlag des Projekts in der App. In Zapier enthält der Datensatz zusätzlich das Feld id: eine Kopie von client_reference_id, die als „Send ID“ angezeigt wird.
{
"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"
}| Feld | Typ | Beschreibung |
|---|---|---|
| client_reference_id | String | Eindeutige ID dieses Sendevorgangs |
| planNumber | String | Projekt-ID |
| planName | String | Projektname |
| revisionUrl | String | Öffentlicher Link zum Projekt |
| revisionNumber | String | Projektrevision |
| erstellt, aktualisiert | String, ISO 8601 | Zeitpunkt, zu dem das Projekt erstellt und zuletzt gespeichert wurde |
| 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 (Notiz des Benutzers zum Artikel oder null), area (m², für Materialien), components[] (Teile des Artikels: dieselben Felder, wobei quantity die Anzahl für alle Einheiten des Artikels angibt, zuzüglich quantityPerItem als Anzahl pro Einheit; im Beispiel entfällt quantityPerItem) |
| price_source | String | company (Preis aus dem Katalog des Unternehmens) oder estimate (Home-Planner-Kostenvoranschlag) |
| source | String | company (Produkt aus dem Katalog des Unternehmens) oder homeplanner (Home-Planner-Katalog) |
| totals | Objekt | items: Anzahl der Hauptpositionen (Komponenten nicht mitgezählt); sum: Gesamtsumme des Kostenvoranschlags inklusive Komponenten; currency: Währungscode |
| pdfUrl | String oder null | Link zur PDF-Datei des Grundrisses; die Datei steht 7 Tage lang zur Verfügung |
| productsText | String | Der vollständige Kostenvoranschlag als Reintext |
| warning | String oder null | Beispiel: „2 Artikel ohne SKU wurden mit einem Home-Planner-Code gesendet“ |
| integration | String | Immer „custom“ |
Ratenbegrenzungen
| Geltungsbereich | Limit |
|---|---|
| Ein Verbindungsschlüssel | 30 Anfragen pro Minute, 500 pro Tag |
| Anfragen mit ungültigem Schlüssel, pro IP-Adresse | 300 pro Minute, 5000 pro Tag |
Bei Überschreitung eines Limits gibt die API 429 mit {"code": "crm_throttled"} zurück.
Fehler
Jeder Fehler wird als JSON mit dem Feld code zurückgegeben, zum Beispiel {"code": "crm_key_invalid"}.
| Status | Code | Bedeutung |
|---|---|---|
| 401 | crm_key_invalid | Fehlender, ungültiger oder ersetzter Schlüssel |
| 422 | crm_url_invalid, crm_url_credentials, crm_url_forbidden | Die Webhook-URL wird abgelehnt |
| 429 | crm_throttled | Ratenbegrenzung erreicht |
| 503 | crm_unavailable | Vorübergehendes Serverproblem; versuche es später erneut |
Unterstützung
Fragen zur API richtest du an: [email protected].
Markenhinweis. Zapier, Make, HubSpot, Pipedrive, Bitrix24, Salesforce und Google Sheets sind Marken ihrer jeweiligen Eigentümer. Home Planner ist von diesen Unternehmen unabhängig und wird von ihnen weder unterstützt noch gesponsert oder steht mit ihnen in Verbindung.
Probiere es in deinem eigenen Projekt aus
Kostenlose Raumplaner- und Einrichtungs-App


