Home Planner
Retour au Centre d'aideGuides pratiques

Référence de l'API CRM de Home Planner

Home Planner
Home PlannerÉquipe App · October 28, 2026

Endpoints, authentification, envoi par webhook et fiche projet de l'API CRM de Home Planner pour Zapier, Make et ton propre serveur.

L'application Home Planner transmet un projet d'aménagement de pièce via Zapier vers HubSpot, Salesforce, Google Sheets et Pipedrive

L'API CRM de Home Planner connecte l'application Home Planner à Zapier, Make et à ton propre serveur. Elle propose quatre endpoints, tous authentifiés par une clé de connexion, ainsi qu'un webhook qui transmet chaque projet envoyé par l'utilisateur.

Cette page s'adresse aux développeurs et aux plateformes d'intégration. Pour configurer l'envoi de projets depuis l'application, consulte Comment envoyer des projets depuis Home Planner vers ton CRM.

Présentation générale

ÉlémentValeur
URL de basehttps://icandesignapp.com (utilise cet hôte : une redirection depuis homeplannerapp.com risquerait de supprimer le corps d'une requête POST)
FormatJSON via HTTPS
AuthentificationClé de connexion dans l'en-tête X-Api-Key
TransmissionWebhook (REST hook) : une requête POST par projet envoyé
Abonnement requisPRO++ (ou sa période d'essai gratuite de 14 jours)

Il existe deux méthodes de connexion :

  1. Connexion par clé — pour Zapier et Make. L'utilisateur sélectionne un CRM dans l'application et copie la clé ; la plateforme enregistre son webhook au moyen d'une requête POST /crm/key/hooks. Cette page détaille ce fonctionnement.
  2. Connexion par URL — pour ton propre serveur. L'utilisateur choisit Autre système (ton URL) dans l'application et y indique l'URL. Aucun endpoint ni aucune clé ne sont requis, et l'application affiche le secret de signature.
MéthodePoint de terminaisonObjectif
GET/crm/key/meValider la clé et renvoyer le nom de la connexion
POST/crm/key/hooksEnregistrer l'URL d'un webhook
DELETE/crm/key/hooks/{id}Supprimer l'enregistrement du webhook
GET/crm/key/sampleObtenir un exemple de fiche projet

Authentification

Chaque requête transmet la clé de connexion dans l'en-tête X-Api-Key. Chaque clé correspond à une seule connexion CRM au sein d'un unique compte Home Planner. Ne place jamais la clé dans une URL.

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

L'utilisateur récupère la clé dans l'application Home Planner :

  1. Ouvre les Réglages et choisis la destination d'envoi des projets.
  2. Sélectionne Ajouter une connexion, puis choisis HubSpot, Pipedrive, Bitrix24, Salesforce ou Google Sheets.
  3. Sélectionne Copier la clé.

Une clé cesse de fonctionner dès que l'utilisateur sélectionne Nouvelle clé ou supprime la connexion. Toute requête comportant une clé manquante, invalide ou remplacée renvoie le code 401 avec {"code": "crm_key_invalid"} (la méthode DELETE fait exception, voir ci-dessous).

GET /crm/key/me

Renvoie la connexion associée à la clé. Zapier l'appelle afin de tester une nouvelle connexion et de lui attribuer un nom.

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

Réponse 200 :

jsonjson
{
  "connectionId": "65f0c3a2e4b0a1b2c3d4e5f7",
  "name": "HubSpot deals",
  "system": "hubspot"
}
ChampTypeDésignation
connectionIdchaîneIdentifiant de la connexion
namechaîneNom de la connexion dans l'application (24 caractères maximum)
systèmechaînehubspot, pipedrive, bitrix24, salesforce ou sheets

Erreurs : 401 crm_key_invalid. Pour les autres erreurs, consulte la section Erreurs ci-dessous.

POST /crm/key/hooks

Définit l'URL du webhook qui reçoit chaque projet envoyé via cette connexion. Zapier l'appelle lorsqu'un Zap est activé.

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

Réponse 201 :

jsonjson
{
  "id": "3f2b9c0d1e4a5b6c7d8e9f01"
}

Conserve l'id : tu en auras besoin pour supprimer l'enregistrement.

  • Un seul enregistrement par connexion : un nouvel enregistrement remplace l'URL précédente.
  • L'URL doit commencer par https://, contenir au maximum 2 048 caractères et ne comporter aucun nom d'utilisateur ni mot de passe.
  • Les URL pointant vers des réseaux privés ou locaux, y compris les noms d'hôte qui y mènent, sont refusées : localhost, 127.*, 10.*, 172.16–31.*, 192.168.* et 169.254.*.
StatutcodeSignification
401crm_key_invalidClé manquante, invalide ou remplacée
422crm_url_invalidL'URL ne commence pas par https:// ou dépasse 2 048 caractères
422crm_url_credentialsL'URL contient un nom d'utilisateur ou un mot de passe
422crm_url_forbiddenL'URL pointe vers un réseau privé ou local

Pour les autres erreurs, consulte la section Erreurs ci-dessous.

DELETE /crm/key/hooks/{id}

Supprime l'enregistrement correspondant à cet id. Zapier l'appelle lorsqu'un Zap est désactivé ou supprimé.

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

Réponse 204 sans corps de réponse. La réponse vaut également 204 si l'identifiant ne correspond pas à l'enregistrement actuel, si la clé a été remplacée ou si la connexion a été supprimée. Dans tous ces cas, il ne reste plus rien à retirer.

Erreurs : 401 crm_key_invalid en cas de clé manquante ou n'ayant jamais été valide. Pour les autres erreurs, consulte la section Erreurs ci-dessous.

GET /crm/key/sample

Renvoie un tableau contenant un exemple de fiche projet au même format qu'un envoi réel. Zapier en affiche les champs pour permettre à l'utilisateur de les associer aux champs du CRM.

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

Réponse 200 : un tableau contenant une fiche projet (voir ci-dessous).

Erreurs : 401 crm_key_invalid. Pour les autres erreurs, consulte la section Erreurs ci-dessous.

Transmission par webhook

Lorsque l'utilisateur sélectionne Partager → Envoyer vers … dans l'application, Home Planner transmet le projet à l'URL enregistrée au moyen d'une requête POST.

ÉlémentValeur
MéthodePOST
Content-Typeapplication/json
CorpsUne fiche projet
X-HomePlanner-DeliveryIdentifiant d'envoi. Il reste identique lors des tentatives de réémission : utilise-le pour détecter les doublons.
X-HomePlanner-Signaturet=<temps Unix en secondes>,v1=<hexadécimal en minuscules>, où v1 = HMAC-SHA256(secret de signature, t + "." + corps brut)
Ta réponseAction de Home Planner
Tout code 2xx sous 15 secondesLivré
Absence de réponse sous 15 secondes, code 5xx, 408 ou 429Nouvelles tentatives au bout de 1 minute, 10 minutes puis 1 heure. Si le projet n'est toujours pas transmis 2 heures après la première tentative, les essais s'arrêtent et l'application indique un statut d'erreur pour cette connexion.
410 GoneConnexion par clé : supprime l'enregistrement ; réactive le Zap pour enregistrer à nouveau le webhook. Connexion par URL : comportement identique à tout autre code 4xx
Tout autre code 4xx, une redirection ou une erreur de certificatAucune nouvelle tentative ; l'application indique un statut d'erreur pour la connexion

Chaque envoi est signé. L'application n'affiche le secret de signature que pour les connexions par URL. Pour connaître les étapes de vérification de la signature, consulte Comment envoyer des projets depuis Home Planner vers ton CRM.

Si l'essai gratuit ou l'abonnement PRO++ de l'utilisateur prend fin, l'application interrompt l'envoi des projets. Les endpoints continuent de répondre : le Zap reste donc actif, mais ne reçoit plus aucun projet jusqu'au réabonnement.

Fiche projet

Chaque envoi ainsi que l'endpoint d'exemple utilisent ce format. Les prix et montants totaux correspondent au devis du projet dans l'application. Dans Zapier, la fiche comprend également un champ id : une copie de client_reference_id, affichée sous le nom Send 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"
}
ChampTypeDésignation
client_reference_idchaîneIdentifiant unique de cet envoi
planNumberchaîneIdentifiant du projet
planNamechaîneNom du projet
revisionUrlchaîneLien public vers le projet
revisionNumberchaîneRévision du projet
créé, mis à jourchaîne, ISO 8601Dates de création et de dernière sauvegarde du projet
rooms[]tableauroomNumber, roomName, roomType, area (m²), height, width, depth (m), items
rooms[].items[]tableauitemNumber (SKU), name, quantity, price, currency, total, price_source, source, imageURL, note (la note de l'utilisateur sur l'article, ou null), area (m², pour les matériaux), components[] (éléments composant l'article : mêmes champs, où quantity correspond au nombre total pour l'ensemble des unités de cet article, auquel s'ajoute quantityPerItem, le nombre par unité ; l'exemple omet quantityPerItem)
price_sourcechaînecompany (prix issu du catalogue d'entreprise) ou estimate (devis Home Planner)
sourcechaînecompany (produit issu du catalogue d'entreprise) ou homeplanner (catalogue Home Planner)
totalsobjetitems : nombre de lignes principales (composants non inclus) ; sum : montant total du devis, composants inclus ; currency : code devise
pdfUrlstring ou nullLien vers le PDF du plan d'étage ; le fichier reste disponible pendant 7 jours
productsTextchaîneL'intégralité du devis au format texte brut
warningstring ou nullPar exemple : "2 article(s) sans SKU ont été envoyés avec un code Home Planner"
intégrationchaîneToujours "custom"

Limites de débit

PortéeLimite
Une clé de connexion30 requêtes par minute, 500 par jour
Requêtes avec une clé invalide, par adresse IP300 par minute, 5 000 par jour

En cas de dépassement d'une limite, l'API renvoie le code 429 avec {"code": "crm_throttled"}.

Erreurs

Chaque erreur est transmise au format JSON avec un champ code, par exemple {"code": "crm_key_invalid"}.

StatutcodeSignification
401crm_key_invalidClé manquante, invalide ou remplacée
422crm_url_invalid, crm_url_credentials, crm_url_forbiddenL'URL du webhook est refusée
429crm_throttledLimite de débit atteinte
503CRM indisponibleProblème serveur temporaire ; réessaie plus tard

Assistance

Des questions sur l'API ? Écris à [email protected].

Mentions de marques. Zapier, Make, HubSpot, Pipedrive, Bitrix24, Salesforce et Google Sheets sont des marques déposées de leurs propriétaires respectifs. Home Planner est indépendant de ces sociétés et n'est ni sponsorisé, ni soutenu, ni affilié à celles-ci.

Home Planner

Essaie sur ton propre projet

Application gratuite de plan de pièce et de design d'intérieur