Referência da API de CRM do Home Planner

Endpoints, autenticação, entrega por webhook e registro de projeto da API de CRM do Home Planner usada pelo Zapier, Make e pelo seu próprio servidor.

A API de CRM do Home Planner conecta o aplicativo Home Planner ao Zapier, ao Make e ao seu próprio servidor. Ela contém quatro endpoints, todos autenticados com uma chave de conexão, e um webhook que envia cada projeto encaminhado pelo usuário.
Esta página é destinada a desenvolvedores e plataformas de integração. Para configurar o envio de projetos no aplicativo, consulte Como enviar projetos do Home Planner para o seu CRM.
Visão geral
| Item | Valor |
|---|---|
| URL base | https://icandesignapp.com (use este host: um redirecionamento de homeplannerapp.com pode descartar o corpo de um POST) |
| Formato | JSON via HTTPS |
| Autenticação | Chave de conexão no cabeçalho X-Api-Key |
| Envio | Webhook (REST hook): um POST por projeto enviado |
| Plano necessário | PRO++ (ou o seu teste grátis de 14 dias) |
Existem duas formas de conectar:
- Conexão por chave — para Zapier e Make. O usuário escolhe um CRM no aplicativo e copia a chave; a plataforma inscreve o seu webhook com POST /crm/key/hooks. Esta página descreve este método.
- Conexão por URL — para o seu próprio servidor. O usuário escolhe Outro sistema (URL próprio) no aplicativo e insere a URL no local indicado. Não são necessários chave nem endpoints, e o aplicativo exibe o segredo de assinatura.
| Método | Endpoint | Finalidade |
|---|---|---|
| GET | /crm/key/me | Validar a chave e retornar o nome da conexão |
| POST | /crm/key/hooks | Inscrever uma URL de webhook |
| DELETE | /crm/key/hooks/{id} | Cancelar a inscrição do webhook |
| GET | /crm/key/sample | Obter um registro de projeto de exemplo |
Autenticação
Cada requisição transporta a chave de conexão no cabeçalho X-Api-Key. Cada chave pertence a uma única conexão de CRM em uma única conta do Home Planner. Nunca insira a chave em uma URL.
X-Api-Key: hp_live_<accountId>_<connectionId>_<version>_<signature>O usuário obtém a chave no aplicativo Home Planner:
- Abra as Configurações e escolha onde enviar os projetos.
- Selecione Adicionar conexão e escolha HubSpot, Pipedrive, Bitrix24, Salesforce ou Google Sheets.
- Selecione Copiar chave.
Uma chave deixa de funcionar quando o usuário seleciona Nova chave ou exclui a conexão. Qualquer requisição com chave ausente, inválida ou substituída retorna 401 com {"code": "crm_key_invalid"} (com exceção do DELETE, veja abaixo).
GET /crm/key/me
Retorna a conexão à qual a chave pertence. O Zapier faz essa chamada para testar uma nova conexão e atribuir um rótulo a ela.
curl https://icandesignapp.com/crm/key/me \
-H 'X-Api-Key: hp_live_…'Resposta 200:
{
"connectionId": "65f0c3a2e4b0a1b2c3d4e5f7",
"name": "HubSpot deals",
"system": "hubspot"
}| Campo | Tipo | Descrição |
|---|---|---|
| connectionId | string | ID da conexão |
| nome | string | Nome da conexão vindo do aplicativo, com até 24 caracteres |
| sistema | string | hubspot, pipedrive, bitrix24, salesforce ou sheets |
Erros: 401 crm_key_invalid. Outros erros: veja Erros abaixo.
POST /crm/key/hooks
Define a URL de webhook que recebe cada projeto enviado por esta conexão. O Zapier faz essa chamada quando um Zap é ativado.
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/"}'Resposta 201:
{
"id": "3f2b9c0d1e4a5b6c7d8e9f01"
}Armazene o id: ele será necessário para cancelar a inscrição.
- Uma inscrição por conexão: uma nova inscrição substitui a URL anterior.
- A URL deve começar com https://, ter no máximo 2048 caracteres e não conter nome de usuário nem senha.
- URLs direcionadas a redes privadas ou locais, incluindo nomes de host que resolvam para elas, serão rejeitadas: localhost, 127.*, 10.*, 172.16–31.*, 192.168.* e 169.254.*.
| Estado | código | Significado |
|---|---|---|
| 401 | crm_key_invalid | Chave ausente, inválida ou substituída |
| 422 | crm_url_invalid | Não é uma URL https:// ou tem mais de 2048 caracteres |
| 422 | crm_url_credentials | A URL contém nome de usuário ou senha |
| 422 | crm_url_forbidden | A URL aponta para uma rede privada ou local |
Outros erros: veja Erros abaixo.
DELETE /crm/key/hooks/{id}
Remove a inscrição correspondente a este id. O Zapier faz essa chamada quando um Zap é desativado ou excluído.
curl -X DELETE https://icandesignapp.com/crm/key/hooks/3f2b9c0d1e4a5b6c7d8e9f01 \
-H 'X-Api-Key: hp_live_…'Resposta 204 sem corpo. A resposta também é 204 se o ID não corresponder à assinatura atual, a chave tiver sido substituída ou a conexão tiver sido excluída. Em cada caso, não há mais nada a remover.
Erros: 401 crm_key_invalid para uma chave ausente ou que nunca tenha sido válida. Outros erros: veja Erros abaixo.
GET /crm/key/sample
Retorna uma matriz contendo um registro de projeto de exemplo com o mesmo formato de uma entrega real. O Zapier exibe seus campos para que o usuário possa mapeá-los para os campos do CRM.
curl https://icandesignapp.com/crm/key/sample \
-H 'X-Api-Key: hp_live_…'Resposta 200: uma matriz contendo um registro de projeto (abaixo).
Erros: 401 crm_key_invalid. Outros erros: veja Erros abaixo.
Entrega por webhook
Quando o usuário seleciona Compartilhar → Enviar para... no aplicativo, o Home Planner envia o projeto via POST para a URL inscrita.
| Parte | Valor |
|---|---|
| Método | POST |
| Content-Type | application/json |
| Corpo | Um registro de projeto |
| X-HomePlanner-Delivery | ID de entrega. Ele permanece o mesmo em caso de novas tentativas: use-o para detectar duplicatas. |
| X-HomePlanner-Signature | t=<tempo unix em segundos>,v1=<hexadecimal em minúsculas>, onde v1 = HMAC-SHA256(segredo de assinatura, t + "." + corpo bruto) |
| Sua resposta | Ação do Home Planner |
|---|---|
| Qualquer 2xx em até 15 segundos | Entregue |
| Sem resposta em até 15 segundos, 5xx, 408 ou 429 | Tenta novamente após 1 minuto, 10 minutos e 1 hora. Se o projeto continuar sem ser entregue 2 horas após a primeira tentativa, interrompe o processo e marca a conexão como Erro no aplicativo. |
| 410 Gone | Conexão por chave: remove a inscrição; ative o Zap novamente para reinscrever. Conexão por URL: o mesmo que qualquer outro 4xx |
| Qualquer outro 4xx, um redirecionamento ou um erro de certificado | Sem novas tentativas; o aplicativo marca a conexão como Erro |
Cada entrega é assinada. O aplicativo exibe o segredo de assinatura apenas para a conexão por URL. Para ver as etapas de verificação da assinatura, consulte Como enviar projetos do Home Planner para o seu CRM.
Quando a assinatura PRO++ ou o período de teste grátis do usuário termina, o aplicativo para de enviar projetos. Os endpoints continuam respondendo, de modo que o Zap permanece ativo, mas sem receber novos projetos até que ocorra a renovação.
Registro de projeto
Todas as entregas e o endpoint de exemplo usam este formato. Preços e totais correspondem ao orçamento do projeto no aplicativo. No Zapier, o registro também contém um campo id: uma cópia do client_reference_id, exibida como ID de envio.
{
"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 | Descrição |
|---|---|---|
| client_reference_id | string | ID exclusivo deste envio |
| planNumber | string | ID do projeto |
| planName | string | Nome do projeto |
| revisionUrl | string | Link público para o projeto |
| revisionNumber | string | Revisão do projeto |
| criado, atualizado | string, ISO 8601 | Quando o projeto foi criado e salvo pela última vez |
| rooms[] | matriz | roomNumber, roomName, roomType, area (m²), height, width, depth (m), items |
| rooms[].items[] | matriz | itemNumber (SKU), name, quantity, price, currency, total, price_source, source, imageURL, note (a observação do usuário no item ou null), area (m², para materiais), components[] (partes do item: os mesmos campos, onde quantity é a contagem para todas as unidades do item, somado a quantityPerItem, a contagem por unidade; o exemplo omite quantityPerItem) |
| price_source | string | company (preço vindo do catálogo da empresa) ou estimate (orçamento do Home Planner) |
| source | string | company (produto vindo do catálogo da empresa) ou homeplanner (Catálogo do Home Planner) |
| totais | objeto | items: número de itens de linha de nível superior (componentes não contados); sum: total do orçamento, componentes incluídos; currency: código da moeda |
| pdfUrl | string ou null | Link para o PDF da planta baixa; o arquivo fica disponível por 7 dias |
| productsText | string | O orçamento completo como texto simples |
| aviso | string ou null | Por exemplo: "2 item(ns) sem SKU foram enviados com um código do Home Planner" |
| integração | string | Sempre "custom" |
Limites de frequência
| Escopo | Limite |
|---|---|
| Uma chave de conexão | 30 requisições por minuto, 500 por dia |
| Requisições com chave inválida, por endereço IP | 300 por minuto, 5000 por dia |
Quando um limite é excedido, a API retorna 429 com {"code": "crm_throttled"}.
Erros
Cada erro é um JSON com um campo code, por exemplo {"code": "crm_key_invalid"}.
| Estado | código | Significado |
|---|---|---|
| 401 | crm_key_invalid | Chave ausente, inválida ou substituída |
| 422 | crm_url_invalid, crm_url_credentials, crm_url_forbidden | A URL de webhook foi recusada |
| 429 | crm_throttled | Limite de frequência atingido |
| 503 | crm_unavailable | Problema temporário no servidor; tente novamente mais tarde |
Suporte
Dúvidas sobre a API: [email protected].
Aviso de marcas registradas. Zapier, Make, HubSpot, Pipedrive, Bitrix24, Salesforce e Google Sheets são marcas registradas dos seus respectivos proprietários. O Home Planner é independente destas empresas e não possui vínculo, patrocínio ou endosso por parte delas.
Experimentar em um projeto próprio
Aplicativo gratuito de planejamento de ambientes e design de interiores


