Home Planner
Voltar para a Central de ajudaGuias passo a passo

Referência da API de CRM do Home Planner

Home Planner
Home PlannerEquipe do aplicativo · October 28, 2026

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.

O aplicativo Home Planner envia um projeto de design de ambiente via Zapier para HubSpot, Salesforce, Google Sheets e Pipedrive

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

ItemValor
URL basehttps://icandesignapp.com (use este host: um redirecionamento de homeplannerapp.com pode descartar o corpo de um POST)
FormatoJSON via HTTPS
AutenticaçãoChave de conexão no cabeçalho X-Api-Key
EnvioWebhook (REST hook): um POST por projeto enviado
Plano necessárioPRO++ (ou o seu teste grátis de 14 dias)

Existem duas formas de conectar:

  1. 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.
  2. 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étodoEndpointFinalidade
GET/crm/key/meValidar a chave e retornar o nome da conexão
POST/crm/key/hooksInscrever uma URL de webhook
DELETE/crm/key/hooks/{id}Cancelar a inscrição do webhook
GET/crm/key/sampleObter 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.

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

O usuário obtém a chave no aplicativo Home Planner:

  1. Abra as Configurações e escolha onde enviar os projetos.
  2. Selecione Adicionar conexão e escolha HubSpot, Pipedrive, Bitrix24, Salesforce ou Google Sheets.
  3. 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.

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

Resposta 200:

jsonjson
{
  "connectionId": "65f0c3a2e4b0a1b2c3d4e5f7",
  "name": "HubSpot deals",
  "system": "hubspot"
}
CampoTipoDescrição
connectionIdstringID da conexão
nomestringNome da conexão vindo do aplicativo, com até 24 caracteres
sistemastringhubspot, 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.

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

Resposta 201:

jsonjson
{
  "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.*.
EstadocódigoSignificado
401crm_key_invalidChave ausente, inválida ou substituída
422crm_url_invalidNão é uma URL https:// ou tem mais de 2048 caracteres
422crm_url_credentialsA URL contém nome de usuário ou senha
422crm_url_forbiddenA 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.

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

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

ParteValor
MétodoPOST
Content-Typeapplication/json
CorpoUm registro de projeto
X-HomePlanner-DeliveryID de entrega. Ele permanece o mesmo em caso de novas tentativas: use-o para detectar duplicatas.
X-HomePlanner-Signaturet=<tempo unix em segundos>,v1=<hexadecimal em minúsculas>, onde v1 = HMAC-SHA256(segredo de assinatura, t + "." + corpo bruto)
Sua respostaAção do Home Planner
Qualquer 2xx em até 15 segundosEntregue
Sem resposta em até 15 segundos, 5xx, 408 ou 429Tenta 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 GoneConexã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 certificadoSem 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.

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"
}
CampoTipoDescrição
client_reference_idstringID exclusivo deste envio
planNumberstringID do projeto
planNamestringNome do projeto
revisionUrlstringLink público para o projeto
revisionNumberstringRevisão do projeto
criado, atualizadostring, ISO 8601Quando o projeto foi criado e salvo pela última vez
rooms[]matrizroomNumber, roomName, roomType, area (m²), height, width, depth (m), items
rooms[].items[]matrizitemNumber (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_sourcestringcompany (preço vindo do catálogo da empresa) ou estimate (orçamento do Home Planner)
sourcestringcompany (produto vindo do catálogo da empresa) ou homeplanner (Catálogo do Home Planner)
totaisobjetoitems: 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
pdfUrlstring ou nullLink para o PDF da planta baixa; o arquivo fica disponível por 7 dias
productsTextstringO orçamento completo como texto simples
avisostring ou nullPor exemplo: "2 item(ns) sem SKU foram enviados com um código do Home Planner"
integraçãostringSempre "custom"

Limites de frequência

EscopoLimite
Uma chave de conexão30 requisições por minuto, 500 por dia
Requisições com chave inválida, por endereço IP300 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"}.

EstadocódigoSignificado
401crm_key_invalidChave ausente, inválida ou substituída
422crm_url_invalid, crm_url_credentials, crm_url_forbiddenA URL de webhook foi recusada
429crm_throttledLimite de frequência atingido
503crm_unavailableProblema 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.

Home Planner

Experimentar em um projeto próprio

Aplicativo gratuito de planejamento de ambientes e design de interiores