Home Planner
Zurück zum Hilfe-CenterAnleitungen

CRM-API-Referenz von Home Planner

Home Planner
Home PlannerApp-Team · October 28, 2026

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

Die Home-Planner-App sendet ein Raumgestaltungsprojekt über Zapier an HubSpot, Salesforce, Google Sheets und Pipedrive

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

EintragWert
Basis-URLhttps://icandesignapp.com (nutze diesen Host; bei einer Weiterleitung von homeplannerapp.com kann der POST-Body verloren gehen)
FormatJSON über HTTPS
AuthentifizierungVerbindungsschlüssel im Header „X-Api-Key“
ÜbertragungWebhook (REST-Hook): ein POST pro gesendetem Projekt
Erforderlicher TarifPRO++ (oder die kostenlose 14-Tage-Testversion)

Es gibt zwei Verbindungsarten:

  1. 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.
  2. 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.
MethodeEndpunktZweck
GET/crm/key/meSchlüssel prüfen und den Verbindungsnamen zurückgeben
POST/crm/key/hooksWebhook-URL abonnieren
DELETE/crm/key/hooks/{id}Webhook-Abonnement kündigen
GET/crm/key/sampleBeispiel-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.

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

Den Schlüssel erhältst du in der Home-Planner-App:

  1. Öffne die Einstellungen und wähle aus, wohin Projekte gesendet werden sollen.
  2. Wähle Verbindung hinzufügen und wähle HubSpot, Pipedrive, Bitrix24, Salesforce oder Google Sheets aus.
  3. 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.

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

Antwort 200:

jsonjson
{
  "connectionId": "65f0c3a2e4b0a1b2c3d4e5f7",
  "name": "HubSpot deals",
  "system": "hubspot"
}
FeldTypBeschreibung
connectionIdStringVerbindungs-ID
NameStringVerbindungsname aus der App, bis zu 24 Zeichen
SystemStringhubspot, 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.

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

Antwort 201:

jsonjson
{
  "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.*.
StatusCodeBedeutung
401crm_key_invalidFehlender, ungültiger oder ersetzter Schlüssel
422crm_url_invalidKeine https://-URL oder länger als 2048 Zeichen
422crm_url_credentialsDie URL enthält einen Benutzernamen oder ein Passwort
422crm_url_forbiddenDie 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.

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

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

TeilWert
MethodePOST
Content-Typeapplication/json
BodyEin Projektdatensatz
X-HomePlanner-DeliveryÜbertragungs-ID. Sie bleibt bei erneuten Zustellversuchen unverändert: Verwende sie zur Erkennung von Duplikaten.
X-HomePlanner-Signaturet=<Unix-Zeit in Sekunden>,v1=<Hexadezimalwert in Kleinbuchstaben>, wobei v1 = HMAC-SHA256(Signaturgeheimnis, t + "." + Roh-Body)
Deine AntwortReaktion von Home Planner
Beliebiger 2xx-Code innerhalb von 15 SekundenZugestellt
Keine Antwort innerhalb von 15 Sekunden, 5xx, 408 oder 429Erneute 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 GoneVerbindung 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 ZertifikatsfehlerKein 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.

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"
}
FeldTypBeschreibung
client_reference_idStringEindeutige ID dieses Sendevorgangs
planNumberStringProjekt-ID
planNameStringProjektname
revisionUrlStringÖffentlicher Link zum Projekt
revisionNumberStringProjektrevision
erstellt, aktualisiertString, ISO 8601Zeitpunkt, zu dem das Projekt erstellt und zuletzt gespeichert wurde
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 (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_sourceStringcompany (Preis aus dem Katalog des Unternehmens) oder estimate (Home-Planner-Kostenvoranschlag)
sourceStringcompany (Produkt aus dem Katalog des Unternehmens) oder homeplanner (Home-Planner-Katalog)
totalsObjektitems: Anzahl der Hauptpositionen (Komponenten nicht mitgezählt); sum: Gesamtsumme des Kostenvoranschlags inklusive Komponenten; currency: Währungscode
pdfUrlString oder nullLink zur PDF-Datei des Grundrisses; die Datei steht 7 Tage lang zur Verfügung
productsTextStringDer vollständige Kostenvoranschlag als Reintext
warningString oder nullBeispiel: „2 Artikel ohne SKU wurden mit einem Home-Planner-Code gesendet“
integrationStringImmer „custom“

Ratenbegrenzungen

GeltungsbereichLimit
Ein Verbindungsschlüssel30 Anfragen pro Minute, 500 pro Tag
Anfragen mit ungültigem Schlüssel, pro IP-Adresse300 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"}.

StatusCodeBedeutung
401crm_key_invalidFehlender, ungültiger oder ersetzter Schlüssel
422crm_url_invalid, crm_url_credentials, crm_url_forbiddenDie Webhook-URL wird abgelehnt
429crm_throttledRatenbegrenzung erreicht
503crm_unavailableVorü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.

Home Planner

Probiere es in deinem eigenen Projekt aus

Kostenlose Raumplaner- und Einrichtungs-App