@horizon-modules/jetimob-crm-integration

Integração completa com o CRM Jetimob para sincronização e conversão de dados imobiliários para o formato PropertyModelV3.

🏠 O que faz

Este pacote oferece uma solução completa para integrar sistemas imobiliários com a API do Jetimob CRM:

• Download automático de imóveis da API Jetimob
• Conversão de dados Jetimob para PropertyModelV3
• Upload para sua API própria
• Profiling genérico de datasets JSON
• Dados de teste para desenvolvimento

📦 Instalação

npm install @horizon-modules/jetimob-crm-integration
# ou
pnpm add @horizon-modules/jetimob-crm-integration

🚀 Uso Rápido

✅ Uso Mais Simples (Recomendado)

// ESM (TypeScript/Módulos modernos)
import { JetimobDownloader } from '@horizon-modules/jetimob-crm-integration'

// CommonJS (JavaScript tradicional)
const { JetimobDownloader } = require('@horizon-modules/jetimob-crm-integration')

// 🎯 Configuração mínima - baseUrl é OPCIONAL!
const downloader = new JetimobDownloader({
  webserviceKey: 'sua_webservice_key_jetimob',
  outputDir: './data/imoveis'
  // baseUrl: automático (https://api.jetimob.com)
})

// Download simples
const result = await downloader.downloadPages({
  startPage: 1,
  endPage: 5,
  pageSize: 100
})

🔧 Configuração Completa (Opcional)

import { 
  JetimobDownloader, 
  JetimobApiClient, 
  ProfilerService,
  convertJetimobToPropertyV3,
  testMocks,
  fakeData
} from '@horizon-modules/jetimob-crm-integration'

// Configuração com baseUrl customizado (opcional)
const downloader = new JetimobDownloader({
  webserviceKey: 'sua_webservice_key_jetimob',
  outputDir: './data/imoveis',
  baseUrl: 'https://api.jetimob.com' // Opcional
})

const result = await downloader.downloadPages({
  startPage: 1,
  endPage: 5,
  pageSize: 100
})

// 2. Upload para sua API
await downloader.uploadToApi({
  endpoint: 'https://sua-api.com/imoveis',
  headers: { 'Authorization': 'Bearer seu_token' }
})

// 3. Conversão manual
const imovelJetimob = await new JetimobApiClient({ webserviceKey }).getImovel(123)
const propertyV3 = convertJetimobToPropertyV3(imovelJetimob)

// 4. Profiling de dados
const profiler = new ProfilerService({
  inputDir: './data',
  outputDir: './output',
  fieldConfigs: {
    'tipo': { maxExamples: 5 },
    'endereco_bairro': { maxExamples: 20 }
  }
})

const profile = await profiler.profile()
console.log(profile.tipo) // ['Residencial', 'Comercial', ...]

🛠️ API

JetimobDownloader

Principais métodos:

• downloadPage(page, pageSize) - Baixa uma página específica
• downloadPages(options) - Baixa múltiplas páginas
• uploadToApi(config) - Envia dados para sua API
• downloadAndUpload(downloadOpts, uploadOpts) - Operação completa

Configuração:

interface JetimobDownloaderConfig {
  webserviceKey: string // Webservice Key da API Jetimob (obrigatório)
  outputDir: string     // Pasta onde salvar arquivos (obrigatório)
  baseUrl?: string      // URL base da API (OPCIONAL - padrão: https://api.jetimob.com)
}

JetimobApiClient

Principais métodos:

• getImoveis(page?, pageSize?) - Lista imóveis
• getImovel(id) - Busca imóvel específico
• testConnection() - Testa conexão com a API

ProfilerService

Ferramenta genérica para análise de datasets JSON:

const profiler = new ProfilerService({
  inputDir: './dados',           // Pasta com arquivos JSON
  outputDir: './saida',         // Onde salvar o relatório  
  fieldConfigs: {
    campo1: { maxExamples: 5 },  // Máximo 5 exemplos
    campo2: { maxExamples: 10 }  // Máximo 10 exemplos
  },
  defaultMaxExamples: 3         // Padrão para outros campos
})

const resultado = await profiler.profile()
// Resultado: { campo1: [valores únicos], campo2: [...] }

Características:

• ✅ Genérico - funciona com qualquer estrutura JSON
• ✅ Arrays concatenados - junta valores de arrays de vários objetos
• ✅ Objetos aninhados - preserva hierarquia (corretor.nome)
• ✅ Ordem alfabética - campos organizados automaticamente
• ✅ Configurável - controle de quantos exemplos por campo

Dados de Teste

import { testMocks, fakeData } from '@horizon-modules/jetimob-crm-integration'

// Mocks para testes
const validData = testMocks.validos      // Dados válidos para testes
const problematicData = testMocks.problematicos  // Casos edge

// Dados falsos para desenvolvimento
const apartments = fakeData.apartamentos
const houses = fakeData.casas
const commercial = fakeData.comerciais  
const land = fakeData.terrenos
const coberturas = fakeData.coberturas

🔧 Configuração via .env

# === JETIMOB API ===
JETIMOB_WEBSERVICE_KEY=sua_webservice_key_jetimob
JETIMOB_START_PAGE=1
JETIMOB_END_PAGE=10
JETIMOB_PAGE_SIZE=100

# === SUA API ===
API_ENDPOINT=https://sua-api.com/imoveis
API_TOKEN=seu_bearer_token
API_BATCH_SIZE=10

# === OPERAÇÃO ===
OPERATION_MODE=download-and-upload  # download-only | upload-only | download-and-upload
DATA_DIR=./data/jetimob-imports

📁 Estrutura de Dados

Entrada (Jetimob)

{
  "codigo": "427",
  "contrato": "Compra",
  "tipo": "Residencial",
  "subtipo": "Cobertura",
  "titulo_anuncio": "Cobertura com 4 dormitórios à venda",
  "observacoes": "Imponente cobertura duplex com vista panorâmica...",
  "valor_venda": 2500000,
  "valor_venda_visivel": true,
  "dormitorios": 4,
  "suites": 3,
  "banheiros": 5,
  "garagens": 3,
  "area_total": 350,
  "area_privativa": 320,
  "endereco_estado": "Rio Grande do Sul",
  "endereco_cidade": "Torres", 
  "endereco_bairro": "Centro",
  "endereco_logradouro": "Rua XV de Novembro",
  "endereco_numero": "250",
  "endereco_cep": "95560000",
  "latitude": "-29.334722",
  "longitude": "-49.727500",
  "situacao": "Desocupado",
  "destaque": "Sem destaque",
  "imagens": [
    {
      "link": "https://s01.jetimgs.com/427_1.jpg",
      "titulo": "Sala de estar",
      "link_thumb": "https://s01.jetimgs.com/427_1_thumb.jpg"
    }
  ]
}

Saída (PropertyV3)

{
  "reference": "427",
  "title": "Cobertura com 4 dormitórios à venda",
  "description": "Imponente cobertura duplex com vista panorâmica...",
  "media_assets": {
    "images": [
      {
        "full": "https://s01.jetimgs.com/427_1.jpg",
        "md": "https://s01.jetimgs.com/427_1_thumb.jpg",
        "sm": "https://s01.jetimgs.com/427_1_thumb.jpg",
        "cover": true
      }
    ]
  },
  "attributes": {
    "operacao": ["Compra"],
    "tipo": "Residencial",
    "subtipo": "Cobertura",
    "valor_venda": 2500000,
    "area_total": 350,
    "area_util": 320,
    "dormitorios": 4,
    "suites": 3,
    "banheiros": 5,
    "vagas": 3,
    "endereco_cep": "95560000",
    "endereco_estado": "Rio Grande do Sul",
    "endereco_cidade": "Torres",
    "endereco_bairro": "Centro",
    "endereco_logradouro": "Rua XV de Novembro",
    "endereco_numero": "250",
    "latitude": -29.334722,
    "longitude": -49.727500,
    "situacao": "Desocupado",
    "destaque": false
  },
  "settings": {
    "currency_unit": "BRL",
    "area_unit": "m2",
    "distance_unit": "meters",
    "exibir_no_mapa": true
  }
}

Profiling

{
  "tipo": ["Residencial", "Comercial", "Rural"],
  "subtipo": ["Casa", "Apartamento", "Cobertura", "Terreno"],
  "endereco_cidade": ["Torres", "Capão da Canoa", "Xangri-lá"],
  "imagens.link": ["foto1.jpg", "foto2.jpg", "foto3.jpg"]
}

🧪 Desenvolvimento

# Instalar dependências
pnpm install

# Build
pnpm build

# Testes
pnpm test

# Typecheck
pnpm typecheck

Scripts de Desenvolvimento

# Download de propriedades reais
node __dev__/scripts/download-properties.js

# Profiling dos dados baixados  
node __dev__/scripts/profile-properties.js

# Gerar dados falsos
pnpm tsx __dev__/scripts/generate-fake-data.ts

# Gerar mocks para testes
pnpm tsx __dev__/scripts/generate-mocks.ts

# Converter downloads para PropertyV3
pnpm convert:downloads

🎯 Casos de Uso

1. Sincronização Automática

Script diário para manter seu sistema atualizado com dados do Jetimob.

2. Migração de Dados

Conversão em lote de propriedades existentes do Jetimob para seu formato.

3. Análise de Dados

Profiling para entender estrutura e qualidade dos dados imobiliários.

4. Desenvolvimento

Dados falsos e mocks para testes e desenvolvimento local.

🔑 Autenticação Jetimob

A API Jetimob utiliza apenas a Webservice Key na URL:

• ✅ Webservice Key: Incluída na URL do endpoint (obrigatória)
• ❌ Headers de autenticação: Não são necessários
• ❌ Bearer tokens: Não são utilizados

// URL de exemplo
https://api.jetimob.com/webservice/{WEBSERVICE_KEY}/imoveis?v=4&page=1&pageSize=100

📝 Licença

MIT

🤝 Contribuição

Este é um pacote interno da Horizon Labs. Para suporte, abra uma issue no repositório principal.