Referencia de la API de CRM de Home Planner

Puntos de extremo, autenticación, entrega de webhooks y registro de proyectos de la API de CRM de Home Planner que utilizan Zapier, Make y tu propio servidor.

La API de CRM de Home Planner conecta la aplicación Home Planner con Zapier, Make y tu propio servidor. Cuenta con cuatro puntos de extremo (autenticados mediante una clave de conexión) y un webhook que entrega cada proyecto que envía el usuario.
Esta página está dirigida a desarrolladores y plataformas de integración. Para configurar el envío de proyectos desde la aplicación, consulta Cómo enviar proyectos desde Home Planner a tu CRM.
Resumen
| Artículo | Valor |
|---|---|
| URL base | https://icandesignapp.com (usa este host: una redirección desde homeplannerapp.com puede descartar el cuerpo de una solicitud POST) |
| Formato | JSON sobre HTTPS |
| Autenticación | Clave de conexión en el encabezado X-Api-Key |
| Entrega | Webhook (REST hook): una solicitud POST por cada proyecto enviado |
| Plan requerido | PRO++ (o su prueba gratuita de 14 días) |
Hay dos formas de conectarse:
- Conexión por clave: para Zapier y Make. El usuario elige un CRM en la aplicación y copia la clave; la plataforma suscribe su webhook mediante POST /crm/key/hooks. En esta página se describe esta opción.
- Conexión por URL: para tu propio servidor. El usuario elige Otro sistema (tu URL) en la aplicación e ingresa la URL ahí. No se necesitan claves ni puntos de extremo, y la aplicación muestra el secreto de firma.
| Método | Punto de extremo | Propósito |
|---|---|---|
| GET | /crm/key/me | Validar la clave y devolver el nombre de la conexión |
| POST | /crm/key/hooks | Suscribir una URL de webhook |
| DELETE | /crm/key/hooks/{id} | Cancelar la suscripción del webhook |
| GET | /crm/key/sample | Obtener un registro de proyecto de muestra |
Autenticación
Cada solicitud incluye la clave de conexión en el encabezado X-Api-Key. Cada clave pertenece a una sola conexión de CRM en una sola cuenta de Home Planner. Nunca coloques la clave en una URL.
X-Api-Key: hp_live_<accountId>_<connectionId>_<version>_<signature>El usuario obtiene la clave en la aplicación Home Planner:
- Abre Ajustes y elige dónde enviar los proyectos.
- Selecciona Agregar conexión y elige HubSpot, Pipedrive, Bitrix24, Salesforce o Google Sheets.
- Selecciona Copiar clave.
Una clave deja de funcionar cuando el usuario selecciona Nueva clave o elimina la conexión. Cualquier solicitud con una clave faltante, no válida o reemplazada devuelve el código 401 con {"code": "crm_key_invalid"} (la excepción es DELETE, consulta más abajo).
GET /crm/key/me
Devuelve la conexión a la que pertenece la clave. Zapier realiza esta llamada para probar una nueva conexión y asignarle una etiqueta.
curl https://icandesignapp.com/crm/key/me \
-H 'X-Api-Key: hp_live_…'Respuesta 200:
{
"connectionId": "65f0c3a2e4b0a1b2c3d4e5f7",
"name": "HubSpot deals",
"system": "hubspot"
}| Campo | Tipo | Descripción |
|---|---|---|
| connectionId | string | ID de la conexión |
| name | string | Nombre de la conexión desde la aplicación (hasta 24 caracteres) |
| system | string | hubspot, pipedrive, bitrix24, salesforce o sheets |
Errores: 401 crm_key_invalid. Para otros errores, consulta la sección Errores más abajo.
POST /crm/key/hooks
Establece la URL de webhook que recibe cada proyecto enviado a través de esta conexión. Zapier realiza esta llamada cuando se activa un Zap.
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/"}'Respuesta 201:
{
"id": "3f2b9c0d1e4a5b6c7d8e9f01"
}Guarda el id: lo necesitarás para cancelar la suscripción.
- Una suscripción por conexión: una nueva suscripción reemplaza la URL anterior.
- La URL debe comenzar con https://, tener una longitud máxima de 2048 caracteres y no incluir nombre de usuario ni contraseña.
- Se rechazan las URL que apunten a redes privadas o locales, incluidos los nombres de host que resuelvan en ellas: localhost, 127.*, 10.*, 172.16–31.*, 192.168.* y 169.254.*.
| Estado | code | Significado |
|---|---|---|
| 401 | crm_key_invalid | Clave faltante, no válida o reemplazada |
| 422 | crm_url_invalid | No es una URL https:// o supera los 2048 caracteres |
| 422 | crm_url_credentials | La URL contiene un nombre de usuario o contraseña |
| 422 | crm_url_forbidden | La URL apunta a una red privada o local |
Para otros errores, consulta la sección Errores más abajo.
DELETE /crm/key/hooks/{id}
Elimina la suscripción con este id. Zapier realiza esta llamada cuando se desactiva o se elimina un Zap.
curl -X DELETE https://icandesignapp.com/crm/key/hooks/3f2b9c0d1e4a5b6c7d8e9f01 \
-H 'X-Api-Key: hp_live_…'Respuesta 204 sin cuerpo. La respuesta también es 204 si el ID no coincide con la suscripción actual, si se reemplazó la clave o si se eliminó la conexión. En cualquiera de estos casos, no queda nada por eliminar.
Errores: 401 crm_key_invalid si falta la clave o si se usa una clave que nunca fue válida. Para otros errores, consulta la sección Errores más abajo.
GET /crm/key/sample
Devuelve un arreglo con un registro de proyecto de muestra en el mismo formato que una entrega real. Zapier muestra sus campos para que el usuario pueda vincularlos con los campos del CRM.
curl https://icandesignapp.com/crm/key/sample \
-H 'X-Api-Key: hp_live_…'Respuesta 200: un arreglo con un registro de proyecto (a continuación).
Errores: 401 crm_key_invalid. Para otros errores, consulta la sección Errores más abajo.
Entrega por webhook
Cuando el usuario selecciona Compartir → Enviar a… en la aplicación, Home Planner envía el proyecto mediante una solicitud POST a la URL suscripta.
| Parte | Valor |
|---|---|
| Método | POST |
| Content-Type | application/json |
| Cuerpo | Un registro de proyecto |
| X-HomePlanner-Delivery | ID de entrega. Se mantiene igual en los reintentos: úsalo para detectar duplicados. |
| X-HomePlanner-Signature | t=<hora Unix en segundos>,v1=<hexadecimal en minúsculas>, donde v1 = HMAC-SHA256(secreto de firma, t + "." + cuerpo sin procesar) |
| Tu respuesta | Lo que hace Home Planner |
|---|---|
| Cualquier respuesta 2xx en un lapso de 15 segundos | Entregado |
| Sin respuesta en 15 segundos, 5xx, 408 o 429 | Reintenta después de 1 minuto, 10 minutos y 1 hora. Si el proyecto aún no se ha entregado 2 horas después del primer intento, se detendrán los reintentos y la aplicación marcará la conexión como Error. |
| 410 Gone | Conexión por clave: elimina la suscripción; vuelve a activar el Zap para suscribirte nuevamente. Conexión por URL: funciona igual que cualquier otro código 4xx |
| Cualquier otro código 4xx, una redirección o un error de certificado | Sin reintentos; la aplicación marca la conexión como Error |
Cada entrega está firmada. La aplicación muestra el secreto de firma únicamente en el caso de las conexiones por URL. Para conocer los pasos de verificación de la firma, consulta Cómo enviar proyectos desde Home Planner a tu CRM.
Cuando finaliza la suscripción PRO++ o la prueba gratuita del usuario, la aplicación deja de enviar proyectos. Los puntos de extremo continúan respondiendo, por lo que el Zap permanece activo, pero no recibirá nuevos proyectos hasta que el usuario renueve la suscripción.
Registro de proyecto
Todas las entregas y el punto de extremo de muestra utilizan este formato. Los precios y los totales coinciden con el presupuesto del proyecto en la aplicación. En Zapier, el registro también incluye un campo id: una copia de client_reference_id, que se muestra como ID de envío.
{
"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"
}| Campo | Tipo | Descripción |
|---|---|---|
| client_reference_id | string | ID único de este envío |
| planNumber | string | ID del proyecto |
| planName | string | Nombre del proyecto |
| revisionUrl | string | Enlace público al proyecto |
| revisionNumber | string | Revisión del proyecto |
| creado, actualizado | string, ISO 8601 | Cuándo se creó el proyecto y cuándo se guardó por última vez |
| rooms[] | arreglo | roomNumber, roomName, roomType, area (m²), height, width, depth (m), items |
| rooms[].items[] | arreglo | itemNumber (SKU), name, quantity, price, currency, total, price_source, source, imageURL, note (la nota del usuario sobre el artículo o null), area (m², para materiales), components[] (partes del artículo: los mismos campos, donde quantity es la cantidad total para todas las unidades del artículo, más quantityPerItem, la cantidad por unidad; la muestra omite quantityPerItem) |
| price_source | string | company (precio del catálogo de la empresa) o estimate (presupuesto de Home Planner) |
| source | string | company (producto del catálogo de la empresa) o homeplanner (catálogo de Home Planner) |
| totals | objeto | items: cantidad de partidas de primer nivel (sin contar componentes); sum: total del presupuesto, incluidos los componentes; currency: código de moneda |
| pdfUrl | string o null | Enlace al PDF del plano de planta; el archivo está disponible durante 7 días |
| productsText | string | El presupuesto completo en texto sin formato |
| warning | string o null | Por ejemplo: "Se enviaron 2 artículos sin SKU con un código de Home Planner" |
| integración | string | Siempre "custom" |
Límites de frecuencia
| Alcance | Límite |
|---|---|
| Una clave de conexión | 30 solicitudes por minuto, 500 por día |
| Solicitudes con una clave no válida, por dirección IP | 300 por minuto, 5000 por día |
Cuando se supera un límite, la API devuelve el código 429 con {"code": "crm_throttled"}.
Errores
Cada error es un objeto JSON con un campo code, por ejemplo {"code": "crm_key_invalid"}.
| Estado | code | Significado |
|---|---|---|
| 401 | crm_key_invalid | Clave faltante, no válida o reemplazada |
| 422 | crm_url_invalid, crm_url_credentials, crm_url_forbidden | Se rechaza la URL de webhook |
| 429 | crm_throttled | Límite de frecuencia alcanzado |
| 503 | crm_unavailable | Problema temporal del servidor; reinténtalo más tarde |
Soporte
Si tienes preguntas sobre la API, escríbenos a [email protected].
Aviso de marcas comerciales. Zapier, Make, HubSpot, Pipedrive, Bitrix24, Salesforce y Google Sheets son marcas comerciales de sus respectivos propietarios. Home Planner es independiente de estas empresas y no cuenta con su respaldo ni patrocinio, ni está afiliada a ellas.
Pruébalo en tu propio proyecto
App gratuita de diseño de interiores y planos de habitaciones


