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

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

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ément | Valeur |
|---|---|
| URL de base | https://icandesignapp.com (utilise cet hôte : une redirection depuis homeplannerapp.com risquerait de supprimer le corps d'une requête POST) |
| Format | JSON via HTTPS |
| Authentification | Clé de connexion dans l'en-tête X-Api-Key |
| Transmission | Webhook (REST hook) : une requête POST par projet envoyé |
| Abonnement requis | PRO++ (ou sa période d'essai gratuite de 14 jours) |
Il existe deux méthodes de connexion :
- 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.
- 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éthode | Point de terminaison | Objectif |
|---|---|---|
| GET | /crm/key/me | Valider la clé et renvoyer le nom de la connexion |
| POST | /crm/key/hooks | Enregistrer l'URL d'un webhook |
| DELETE | /crm/key/hooks/{id} | Supprimer l'enregistrement du webhook |
| GET | /crm/key/sample | Obtenir 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.
X-Api-Key: hp_live_<accountId>_<connectionId>_<version>_<signature>L'utilisateur récupère la clé dans l'application Home Planner :
- Ouvre les Réglages et choisis la destination d'envoi des projets.
- Sélectionne Ajouter une connexion, puis choisis HubSpot, Pipedrive, Bitrix24, Salesforce ou Google Sheets.
- 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.
curl https://icandesignapp.com/crm/key/me \
-H 'X-Api-Key: hp_live_…'Réponse 200 :
{
"connectionId": "65f0c3a2e4b0a1b2c3d4e5f7",
"name": "HubSpot deals",
"system": "hubspot"
}| Champ | Type | Désignation |
|---|---|---|
| connectionId | chaîne | Identifiant de la connexion |
| name | chaîne | Nom de la connexion dans l'application (24 caractères maximum) |
| système | chaîne | hubspot, 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é.
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 :
{
"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.*.
| Statut | code | Signification |
|---|---|---|
| 401 | crm_key_invalid | Clé manquante, invalide ou remplacée |
| 422 | crm_url_invalid | L'URL ne commence pas par https:// ou dépasse 2 048 caractères |
| 422 | crm_url_credentials | L'URL contient un nom d'utilisateur ou un mot de passe |
| 422 | crm_url_forbidden | L'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é.
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.
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ément | Valeur |
|---|---|
| Méthode | POST |
| Content-Type | application/json |
| Corps | Une fiche projet |
| X-HomePlanner-Delivery | Identifiant d'envoi. Il reste identique lors des tentatives de réémission : utilise-le pour détecter les doublons. |
| X-HomePlanner-Signature | t=<temps Unix en secondes>,v1=<hexadécimal en minuscules>, où v1 = HMAC-SHA256(secret de signature, t + "." + corps brut) |
| Ta réponse | Action de Home Planner |
|---|---|
| Tout code 2xx sous 15 secondes | Livré |
| Absence de réponse sous 15 secondes, code 5xx, 408 ou 429 | Nouvelles 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 Gone | Connexion 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 certificat | Aucune 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.
{
"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"
}| Champ | Type | Désignation |
|---|---|---|
| client_reference_id | chaîne | Identifiant unique de cet envoi |
| planNumber | chaîne | Identifiant du projet |
| planName | chaîne | Nom du projet |
| revisionUrl | chaîne | Lien public vers le projet |
| revisionNumber | chaîne | Révision du projet |
| créé, mis à jour | chaîne, ISO 8601 | Dates de création et de dernière sauvegarde du projet |
| rooms[] | tableau | roomNumber, roomName, roomType, area (m²), height, width, depth (m), items |
| rooms[].items[] | tableau | itemNumber (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_source | chaîne | company (prix issu du catalogue d'entreprise) ou estimate (devis Home Planner) |
| source | chaîne | company (produit issu du catalogue d'entreprise) ou homeplanner (catalogue Home Planner) |
| totals | objet | items : nombre de lignes principales (composants non inclus) ; sum : montant total du devis, composants inclus ; currency : code devise |
| pdfUrl | string ou null | Lien vers le PDF du plan d'étage ; le fichier reste disponible pendant 7 jours |
| productsText | chaîne | L'intégralité du devis au format texte brut |
| warning | string ou null | Par exemple : "2 article(s) sans SKU ont été envoyés avec un code Home Planner" |
| intégration | chaîne | Toujours "custom" |
Limites de débit
| Portée | Limite |
|---|---|
| Une clé de connexion | 30 requêtes par minute, 500 par jour |
| Requêtes avec une clé invalide, par adresse IP | 300 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"}.
| Statut | code | Signification |
|---|---|---|
| 401 | crm_key_invalid | Clé manquante, invalide ou remplacée |
| 422 | crm_url_invalid, crm_url_credentials, crm_url_forbidden | L'URL du webhook est refusée |
| 429 | crm_throttled | Limite de débit atteinte |
| 503 | CRM indisponible | Problè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.
Essaie sur ton propre projet
Application gratuite de plan de pièce et de design d'intérieur


