Home Planner
Volver al Centro de ayudaGuías paso a paso

Referencia de la API de CRM de Home Planner

Home Planner
Home PlannerEquipo de la app · October 28, 2026

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 aplicación Home Planner envía un proyecto de diseño de habitación mediante Zapier a HubSpot, Salesforce, Google Sheets y Pipedrive

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ículoValor
URL basehttps://icandesignapp.com (usa este host: una redirección desde homeplannerapp.com puede descartar el cuerpo de una solicitud POST)
FormatoJSON sobre HTTPS
AutenticaciónClave de conexión en el encabezado X-Api-Key
EntregaWebhook (REST hook): una solicitud POST por cada proyecto enviado
Plan requeridoPRO++ (o su prueba gratuita de 14 días)

Hay dos formas de conectarse:

  1. 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.
  2. 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étodoPunto de extremoPropósito
GET/crm/key/meValidar la clave y devolver el nombre de la conexión
POST/crm/key/hooksSuscribir una URL de webhook
DELETE/crm/key/hooks/{id}Cancelar la suscripción del webhook
GET/crm/key/sampleObtener 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.

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

El usuario obtiene la clave en la aplicación Home Planner:

  1. Abre Ajustes y elige dónde enviar los proyectos.
  2. Selecciona Agregar conexión y elige HubSpot, Pipedrive, Bitrix24, Salesforce o Google Sheets.
  3. 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.

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

Respuesta 200:

jsonjson
{
  "connectionId": "65f0c3a2e4b0a1b2c3d4e5f7",
  "name": "HubSpot deals",
  "system": "hubspot"
}
CampoTipoDescripción
connectionIdstringID de la conexión
namestringNombre de la conexión desde la aplicación (hasta 24 caracteres)
systemstringhubspot, 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.

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

Respuesta 201:

jsonjson
{
  "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.*.
EstadocodeSignificado
401crm_key_invalidClave faltante, no válida o reemplazada
422crm_url_invalidNo es una URL https:// o supera los 2048 caracteres
422crm_url_credentialsLa URL contiene un nombre de usuario o contraseña
422crm_url_forbiddenLa 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.

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

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

ParteValor
MétodoPOST
Content-Typeapplication/json
CuerpoUn registro de proyecto
X-HomePlanner-DeliveryID de entrega. Se mantiene igual en los reintentos: úsalo para detectar duplicados.
X-HomePlanner-Signaturet=<hora Unix en segundos>,v1=<hexadecimal en minúsculas>, donde v1 = HMAC-SHA256(secreto de firma, t + "." + cuerpo sin procesar)
Tu respuestaLo que hace Home Planner
Cualquier respuesta 2xx en un lapso de 15 segundosEntregado
Sin respuesta en 15 segundos, 5xx, 408 o 429Reintenta 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 GoneConexió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 certificadoSin 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.

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"
}
CampoTipoDescripción
client_reference_idstringID único de este envío
planNumberstringID del proyecto
planNamestringNombre del proyecto
revisionUrlstringEnlace público al proyecto
revisionNumberstringRevisión del proyecto
creado, actualizadostring, ISO 8601Cuándo se creó el proyecto y cuándo se guardó por última vez
rooms[]arregloroomNumber, roomName, roomType, area (m²), height, width, depth (m), items
rooms[].items[]arregloitemNumber (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_sourcestringcompany (precio del catálogo de la empresa) o estimate (presupuesto de Home Planner)
sourcestringcompany (producto del catálogo de la empresa) o homeplanner (catálogo de Home Planner)
totalsobjetoitems: cantidad de partidas de primer nivel (sin contar componentes); sum: total del presupuesto, incluidos los componentes; currency: código de moneda
pdfUrlstring o nullEnlace al PDF del plano de planta; el archivo está disponible durante 7 días
productsTextstringEl presupuesto completo en texto sin formato
warningstring o nullPor ejemplo: "Se enviaron 2 artículos sin SKU con un código de Home Planner"
integraciónstringSiempre "custom"

Límites de frecuencia

AlcanceLímite
Una clave de conexión30 solicitudes por minuto, 500 por día
Solicitudes con una clave no válida, por dirección IP300 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"}.

EstadocodeSignificado
401crm_key_invalidClave faltante, no válida o reemplazada
422crm_url_invalid, crm_url_credentials, crm_url_forbiddenSe rechaza la URL de webhook
429crm_throttledLímite de frecuencia alcanzado
503crm_unavailableProblema 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.

Home Planner

Pruébalo en tu propio proyecto

App gratuita de diseño de interiores y planos de habitaciones