n8n-nodes-imobzi-latest

Node customizado para integração com a API da Imobzi no n8n.

🆕 Novidades v2.14.0

FASE 1 COMPLETA - CRUD (100% Testado)

• ✅ Transação Financeira: Get by ID, Create, Update, Delete
• ✅ Calendário: Create, Update, Delete atividades
• ✅ Locação: Create, Update, Delete contratos
• ✅ Fatura: Create, Update faturas
• ✅ Deal Get by ID: Bug corrigido pela Imobzi!

FASE 2 - NOVOS RECURSOS (Testados)

• ✅ Histórico (Timeline): Buscar/criar histórico do contato
• ✅ Reserva de Imóvel: Criar/cancelar reservas

❌ Removidos (API não autorizada)

• Proposta (erro 401)
• Match de Imóveis (erro 401)

📋 Recursos Disponíveis

Recursos Principais (CRUD Completo)

| Recurso | Operações | |---------|-----------| | Contato | Listar, Buscar por ID, Buscar por Código, Verificar Existência, Criar, Atualizar, Deletar | | Imóvel | Listar, Buscar por ID, Buscar por Código, Estatísticas, Criar, Atualizar, Deletar | | Locação | Listar, Buscar por ID, Criar, Atualizar, Deletar ✨ | | Fatura | Listar, Buscar por ID, Criar, Atualizar ✨ | | Funil (Deal) | Listar, Buscar por ID, Criar, Atualizar | | Funil Por Estágio | Listar (visão Kanban) | | Transação Financeira | Listar, Buscar por ID, Criar, Atualizar, Deletar ✨ | | Calendário | Listar, Criar, Atualizar, Deletar atividades ✨ | | Documento | Listar | | Usuário | Listar |

Novos Recursos (Fase 2) ✨

| Recurso | Operações | |---------|-----------| | Histórico (Timeline) | Listar histórico, Criar nota | | Reserva de Imóvel | Listar, Criar, Cancelar reservas |

Recursos Auxiliares (para dropdowns)

• Estágio (Pipeline)
• Grupo de Funil
• Tipo de Imóvel
• Origem (Media Source)
• Tag de Contato
• Motivo de Perda
• Banco
• Conta Financeira

🚀 Instalação

Via npm (recomendado)

npm install n8n-nodes-imobzi-latest -g

No n8n Cloud

1. Vá em Settings > Community Nodes
2. Clique em Install a community node
3. Digite: n8n-nodes-imobzi-latest
4. Clique em Install

VPS / Self-hosted

cd ~/.n8n/nodes
npm install n8n-nodes-imobzi-latest
# Reiniciar n8n
pm2 restart n8n

⚙️ Configuração

Obter API Key

1. Acesse sua conta Imobzi
2. Vá em Configurações > Integrações > API
3. Copie sua API Key

Configurar no n8n

1. Adicione um node Imobzi
2. Clique em Create New Credential
3. Cole sua API Key
4. Salve

📖 Uso

Listar Contatos

Recurso: Contato
Operação: Get Many
Filtros:
  - Usuário Responsável: Dropdown com 16 usuários
  - Origem: Dropdown com 38 opções
  - Tags: Dropdown com 57 opções
  - Smart List: Meus Contatos, Novos Leads, etc

Criar/Atualizar Contato

Recurso: Contato
Operação: Criar / Atualizar
Tipo de Contato: Pessoa/Lead/Organização
Dados (JSON):
{
  "name": "Nome do Contato",
  "email": "[email protected]",
  "phones": [{"number": "67999999999"}]
}

Listar Transações Financeiras

Recurso: Transação Financeira
Operação: Get Many
Filtros:
  - Data Início / Data Fim
  - Status: Pago / Pendente
  - Tipo: Receita / Despesa
  - Conta Bancária
  - Ordenar Por / Ordem

Listar Calendário

Recurso: Calendário
Operação: Get Many
Ano: 2025
Mês: Dezembro
Filtros:
  - Usuário: Dropdown (Todos ou específico)
  - Tipo de Item: Visita/Tarefa/WhatsApp/Chamada
  - Exibir Feriados: Sim/Não

🔧 Auto-Paginação

O node suporta auto-paginação automática. Selecione a quantidade de registros:

• 50 registros
• 100 registros
• 200 registros
• 500 registros
• Todos (máx 5000)

📊 Filtros Disponíveis (v2.9.0)

Contato

• ⚠️ Usuário Responsável: Dropdown com 16 usuários - Não funciona na API
• ✅ Origem: Dropdown com 38 origens
• ✅ Tags: Dropdown com 57 tags (sistema + personalizadas)
• ✅ Smart List: 12 opções (all, my_contacts, new_leads, etc.)
• ⚠️ Tipo de Contato: person ✅, lead ⚠️, organization ❌
• Busca: Por nome, email ou telefone

Imóvel

• ✅ Corretor: Dropdown com 16 usuários
• ✅ Smart List: 16 opções (available, rent, sale, without_photos, etc.)
• ⚠️ Status: available, reserved, unavailable - Não confirmado
• ⚠️ Finalidade: residential, commercial, rural - Não confirmado

Locação

• ✅ Smart List: 9 opções (active, inactive, expiring, finished, etc.)

Fatura - v2.12.0 ✅ CONFIRMADO

• ✅ Período: 15, 30, 60, 90 dias, Personalizado ou Todos
• ✅ Status: pending, paid, overdue, canceled (1 L!), partially_paid, expired, deleted, all
• ✅ Método de Pagamento: bank_slip, pix, credit_card
• ✅ Ordenar Por / Ordem
• ⚠️ status=cancelled: Com 2 L's causa erro 422 (usar canceled)

Deal (Lista) - v2.12.0 ✅ ATUALIZADO

Agora usa /v1/deals com filtros extensivamente testados:

• ✅ Grupo de Funil: Todos + 5 grupos
• ✅ Etapa: Todas + 7 estágios
• ✅ Status do Deal: all (233), win (19), lost (220), stagnant (229), property_radar (100), out_of_date (201)
• ✅ Tipo de Negócio: all (233), rent (138)
• ✅ Corretor: Todos + 16 usuários
• 📤 Output: Lista plana de deals

Deal Por Estágio (Kanban)

Mesmos filtros do Deal (Lista):

• ✅ Grupo de Funil: Todos + 5 grupos
• ✅ Etapa: Todas + 7 estágios
• ✅ Status do Deal: 6 opções testadas (win, lost, stagnant, property_radar, out_of_date, all)
• ✅ Tipo de Negócio: all, rent
• ✅ Corretor: Todos + 16 usuários
• 📤 Output: Estrutura Kanban (deals agrupados por estágio)

Transação Financeira

• ✅ Data Início / Data Fim: Período de busca
• ✅ Status: Pago, Pendente, Todos
• ✅ Tipo: Receita, Despesa, Transferência
• ✅ Conta Bancária: Dropdown dinâmico
• ✅ Ordenar Por: Data de Vencimento, Data de Pagamento, Valor
• ✅ Ordem: Crescente, Decrescente

Calendário - v2.12.0 ✅ ATUALIZADO

• ✅ Usuário: Dropdown (Todos ou específico)
• ✅ Tipo de Item: task (461 itens), whatsapp (326), visit, call
• ✅ Exibir Feriados: Sim/Não
• ⚠️ item_type=all/meeting: Causam erro 422 (não suportados pela API)

🔗 Webhook

O pacote inclui também o node Imobzi Trigger para receber webhooks da Imobzi.

Eventos suportados:

• contact.created / contact.updated
• property.created / property.updated
• deal.created / deal.updated / deal.lost / deal.won
• lease.created
• invoice.created / invoice.paid
• visit.scheduled / visit.cancelled
• E outros...

📝 Notas Importantes

CRUD

• Create: POST para criar novos registros
• Update: POST para atualizar (API Imobzi não usa PATCH)
• Delete: DELETE para remover registros

Paginação

• Contacts: A API ignora o limite e sempre retorna 50 por página (auto-paginação via cursor)
• Invoices e Transactions: Usam next_page (número) para paginação
• Outros: Usam cursor para paginação

IDs

• Usuários: STRING (ex: "P1ibK4GFPqZYKIx9e55RpQobt7J2")
• Contatos/Imóveis: STRING numérica
• Locações/Pipelines: NUMBER
• Faturas: STRING UUID

⚠️ Limitações Conhecidas da API (v2.9.0)

| Endpoint | Problema | |----------|----------| | /v1/contacts?user_id= | Não filtra - sempre retorna todos | | /v1/deals/search?user_id= | Não filtra | | /v1/deals/search?pipeline_id= | Não filtra | | /v1/deal/{id} | Bug - Retorna erro 500 | | /v1/organization/code/{code} | Retorna 404 | | /v1/lead/code/{code} | Retorna 404 | | /v1/property/exists?code= | Retorna dados incorretos |

Soluções

• Para filtrar Deals: Use "Deal Por Estágio" com pipeline_group_id
• Para buscar contato por código: Só funciona para tipo "Pessoa"

📋 Histórico de Versões

v2.14.0 (Atual) ✨

• ✅ FASE 1 COMPLETA: CRUD para Transação, Calendário, Locação, Fatura
• ✅ FASE 2: Timeline, Reserva de Imóvel (testados e funcionando)
• ✅ Deal Get by ID: Bug corrigido pela Imobzi!
• ❌ Removidos: Proposta e Match de Imóveis (API erro 401)
• ✅ 28 endpoints testados: 100% funcionando

v2.13.0

• ✅ FASE 1 COMPLETA: CRUD para Transação, Calendário, Locação, Fatura
• ✅ FASE 2: Timeline, Proposta, Reserva, Match de Imóveis

v2.12.0

• ✅ DEALS Status: Adicionados win, stagnant, property_radar, out_of_date
• ✅ DEALS Tipo: Adicionado rent (138 deals de locação)
• ✅ Calendário item_type: Filtro atualizado com task (461), whatsapp (326)
• ✅ Faturas: Confirmado canceled (1 L), não cancelled (2 L's)
• ✅ +250 testes: Todos os filtros extensivamente testados

v2.11.0

• ✅ DEALS user_id: Corrigido filtro "Todos Os Corretores"
• ✅ CALENDÁRIO: Lógica corrigida para usar search_all=true

v2.10.0

• ✅ Deal (Lista): Agora usa /v1/deals com todos os filtros
• ✅ Filtro de Etapa: Adicionado em Deal e Deal Por Estágio
• ✅ Output Lista Plana: Deals extraídos da estrutura Kanban
• ✅ Todos os filtros têm "Todos": Consistência em todos os nodes

v2.9.0

• Deal Por Estágio: Pipeline Groups (5 grupos) + Pipelines (7 estágios)
• Avisos visuais: Filtros que não funcionam marcados com ⚠️
• Documentação: Mapeamento completo de filtros da API

v2.8.0

• Análise completa de todos os filtros da API
• Documento de mapeamento consolidado

v2.6.0

• Transações Financeiras: 7 filtros completos
• CRUD Contato, Imóvel, Deal

v2.5.0

• Calendar corrigido
• 57 Tags, 38 Origens, 16 Usuários em dropdowns

📄 Licença

MIT © Bruno Mantovani

🔗 Links

• Imobzi
• n8n
• Repositório
• npm

📞 Suporte

• Issues: GitHub Issues
• Email: [email protected]

Versão: 2.14.0
Última atualização: 14 Dezembro 2025
Testes: 28 endpoints testados - 100% funcionando
Changelog: docs/CHANGELOG_v2.14.md