@horizon-integrations/si9-crm 1.1.6 → 1.1.7

package/FICHA_TECNICA_INTEGRACAO.md

@@ -0,0 +1,547 @@
+# SI9 — Ficha Técnica de Integração
+
+> Diretrizes para IAs e desenvolvedores integrarem os dados do CRM SI9 em qualquer site imobiliário.
+> Contém o que o CRM oferece, o que não oferece, limitações, e como tirar o melhor proveito.
+
+**Versão:** 1.0
+**CRM:** SI9 Sistemas
+**Pacote:** @horizon-integrations/si9-crm
+**API:** REST JSON (OAuth 2.0)
+**Base URL:** https://api.si9sistemas.com.br/imobilsi9-api
+
+---
+
+## 1. VISÃO GERAL
+
+O SI9 é um CRM regional focado em imobiliárias de pequeno e médio porte. A API retorna dados de imóveis em JSON com objetos aninhados (generalData, values, features, security, recreation, rural, location, website, destination, company, images, fields).
+
+### Pontos fortes:
+- Campos personalizados (`fields[]`) com chave-valor livre — permite criar campos que a API não tem nativamente
+- 10 situações comerciais documentadas (AVALIABLE, SOLD, RENTED, RESERVED, etc.)
+- Booleans separados por grupo (features, security, recreation, rural) — bom pra categorizar
+- Lat/lng disponíveis (embora não documentados oficialmente)
+
+### Limitações:
+- Sem timestamps da API (sem created_at nem updated_at do imóvel)
+- Sem fotos em múltiplos tamanhos (só URL única)
+- Sem paginação — retorna TODOS os imóveis de uma vez
+- Sem vínculo corretor↔imóvel nativo (precisa de campo personalizado)
+- Sem campos de SEO na API (existem no CRM mas não são expostos)
+- Sem subtipo nativo
+- Sem campo de aceita pet, aceita financiamento, exclusividade na API
+
+---
+
+## 2. CAMPOS HORIZON BASE (45 campos)
+
+Como o SI9 alimenta cada campo base universal:
+
+| Campo base | Fonte SI9 | Tipo | Observação |
+|---|---|---|---|
+| reference | `id` | number→string | Converter pra string |
+| title | `generalData.title` | string | — |
+| description | `generalData.description` | string | — |
+| source_updated_at | — | — | Gerar com `new Date().toISOString()` (API não fornece) |
+| source_published_at | — | — | Não disponível na API |
+| currency | — | — | Fixo "BRL" |
+| unit_area | — | — | Fixo "m2" |
+| unit_distance | — | — | Fixo "meters" |
+| operacao | `destination.sale/rent/season` | booleans→array | sale→"venda", rent→"locacao", season→"temporada" |
+| tipo | `generalData.category.name` | string | 11 tipos encontrados nos dados |
+| valor_venda | `values.saleValue` | number | REAIS (não centavos). Só se destination.sale=true |
+| valor_locacao | `values.rentValue` | number | REAIS. Só se destination.rent=true |
+| valor_condominio | `values.condominiumFee` | number | REAIS |
+| valor_iptu | `values.iptuValue` | number | REAIS. Valor ANUAL |
+| dormitorios | `features.bedroom` | integer | — |
+| suites | `features.suite` | integer | — |
+| banheiros | `features.bathroom` | integer | Só bathroom (toilet/lavabo é campo extra separado) |
+| vagas_garagem | `features.coveredGarage + features.outdoorGarage` | integer | Soma cobertas + descobertas |
+| area_total | `dimensions.totalArea` | number | m² |
+| area_privativa | `dimensions.privateArea` | number | m² |
+| area_util | `dimensions.usefulArea` | number | m² |
+| destaque | `website.highlight \|\| website.superHighlight` | boolean | true se qualquer um true |
+| endereco_cep | `location.zipCode` | string | Vem sem formatação (8 dígitos). Formatar 00000-000 |
+| endereco_estado | `location.city.state` | string | UF |
+| endereco_cidade | `location.city.name` | string | — |
+| endereco_bairro | `location.district.name` | string | — |
+| endereco_logradouro | `location.address` | string | — |
+| endereco_numero | `location.number` | string | — |
+| endereco_complemento | `location.complement` | string | — |
+| endereco_referencia | `location.referencePoint` | string | — |
+| endereco_zona | — | — | Não disponível |
+| lat | `location.latitude` | string→number | Vem como string, converter pra number |
+| lng | `location.longitude` | string→number | Vem como string, converter pra number |
+| corretor_key | — | — | Não disponível nativamente. Usar campo personalizado "Corretor" |
+| corretor_nome | — | — | Idem — campo personalizado "Corretor" com o nome |
+| condominio_key | — | — | Não disponível |
+| condominio_nome | `generalData.allotment` | string | Nome do empreendimento/loteamento/edifício |
+| seo_slug | — | — | Não disponível na API |
+| seo_title | — | — | Não disponível na API |
+| seo_description | — | — | Não disponível na API |
+| seo_keywords | — | — | Não disponível na API |
+| main_image | `images[0]` | object | Filtrar displaySite=true. Primeira imagem |
+| images | `images[]` | array | Filtrar displaySite=true |
+| videos | `generalData.urlVideo` | string→array | Array com 1 item se existir |
+| virtual_tours | `generalData.urlTour` | string→array | Array com 1 item se existir |
+
+---
+
+## 3. CAMPOS EXTRAS DO CRM
+
+Campos adicionais que o SI9 fornece além dos 45 base. Normalizados em snake_case com prefixo do grupo de origem.
+
+### Valores extras
+
+| Campo normalizado | Fonte SI9 | Tipo | SQL |
+|---|---|---|---|
+| values_discount_value | values.discountValue | number | DOUBLE PRECISION |
+| values_fci_value | values.fciValue | number | DOUBLE PRECISION |
+| values_assigned_value | values.assignedValue | number | DOUBLE PRECISION |
+| values_trash_fee | values.trashFee | number | DOUBLE PRECISION |
+| values_disaster_fee | values.disasterFee | number | DOUBLE PRECISION |
+
+### Dados gerais extras
+
+| Campo normalizado | Fonte SI9 | Tipo | SQL |
+|---|---|---|---|
+| general_data_situation | generalData.situation | string (enum) | TEXT |
+| general_data_board | generalData.board | string | TEXT |
+
+### Website extras
+
+Mapeamento dos campos do painel SI9 "Integração com o Site":
+
+| Campo no painel SI9 | Campo na API | Campo normalizado | SQL |
+|---|---|---|---|
+| **Exibe Web** | **NÃO EXPOSTO NA API** | — | — |
+| **Núcleo** | `website.showInCore` | `website_show_in_core` | BOOLEAN |
+| **Minha Casa Minha Vida** | `website.mcmv` | `website_mcmv` | BOOLEAN |
+| **Destaque** | `website.highlight` | (usado no campo base `destaque`) | BOOLEAN |
+| **Super Destaque** | `website.superHighlight` | `website_super_highlight` | BOOLEAN |
+| **Destaque Premium** | **NÃO EXPOSTO NA API** | — | — |
+
+**Limitação:** O campo "Exibe Web" (que controla se o imóvel aparece no site) e "Destaque Premium" NÃO são expostos pela API da SI9. A API provavelmente já filtra internamente e só retorna imóveis com "Exibe Web = Sim".
+
+| Campo normalizado | Fonte SI9 | Tipo | SQL |
+|---|---|---|---|
+| website_super_highlight | website.superHighlight | boolean | BOOLEAN |
+| website_show_in_core | website.showInCore | boolean | BOOLEAN |
+| website_mcmv | website.mcmv | boolean | BOOLEAN |
+
+### Destination extras
+
+| Campo normalizado | Fonte SI9 | Tipo | SQL |
+|---|---|---|---|
+| destination_exchange | destination.exchange | boolean | BOOLEAN |
+
+### Localização complementar
+
+| Campo normalizado | Fonte SI9 | Tipo | SQL |
+|---|---|---|---|
+| location_apartment | location.apartment | string | TEXT |
+| location_block | location.block | string | TEXT |
+| location_floor | location.floor | string | TEXT |
+| location_quatrain | location.quatrain | string | TEXT |
+| location_lot | location.lot | string | TEXT |
+
+### Dimensões extras
+
+| Campo normalizado | Fonte SI9 | Tipo | SQL |
+|---|---|---|---|
+| dimensions_building_area | dimensions.buildingArea | number | DOUBLE PRECISION |
+| dimensions_land_area | dimensions.landArea | number | DOUBLE PRECISION |
+| dimensions_internal_area | dimensions.internalArea | number | DOUBLE PRECISION |
+| dimensions_registered_area | dimensions.registeredArea | number | DOUBLE PRECISION |
+| dimensions_common_area | dimensions.commonArea | number | DOUBLE PRECISION |
+| dimensions_garage_area | dimensions.garageArea | number | DOUBLE PRECISION |
+| dimensions_front_size | dimensions.frontSize | number | DOUBLE PRECISION |
+| dimensions_funds_size | dimensions.fundsSize | number | DOUBLE PRECISION |
+| dimensions_left_size | dimensions.leftSize | number | DOUBLE PRECISION |
+| dimensions_right_size | dimensions.rightSize | number | DOUBLE PRECISION |
+
+### Features (booleans agrupados + numéricos/strings individuais)
+
+| Campo normalizado | Fonte SI9 | Tipo | SQL |
+|---|---|---|---|
+| features | booleans features→labels PT-BR | string[] | TEXT[] |
+| features_room | features.room | integer | INTEGER |
+| features_kitchen | features.kitchen | integer | INTEGER |
+| features_closet | features.closet | integer | INTEGER |
+| features_balcony | features.balcony | integer | INTEGER |
+| features_ar_condicionado | features.arCondicionado | integer | INTEGER |
+| features_toilet | features.toilet | integer | INTEGER |
+| features_floor | features.floor | string | TEXT |
+| features_roof | features.roof | string | TEXT |
+| features_ceiling | features.ceiling | string | TEXT |
+| features_paving | features.paving | string | TEXT |
+| features_pavement | features.pavement | string (enum) | TEXT |
+
+### Security (booleans agrupados)
+
+| Campo normalizado | Fonte SI9 | Tipo | SQL |
+|---|---|---|---|
+| security | booleans security→labels PT-BR | string[] | TEXT[] |
+
+### Recreation (booleans agrupados + enums)
+
+| Campo normalizado | Fonte SI9 | Tipo | SQL |
+|---|---|---|---|
+| recreation | booleans recreation→labels PT-BR | string[] | TEXT[] |
+| recreation_heating | recreation.heating | string (enum) | TEXT |
+| recreation_position_sun | recreation.positionSun | string (enum) | TEXT |
+| recreation_position_court | recreation.positionCourt | string (enum) | TEXT |
+
+### Rural (booleans agrupados + numéricos/strings)
+
+| Campo normalizado | Fonte SI9 | Tipo | SQL |
+|---|---|---|---|
+| rural | booleans rural→labels PT-BR | string[] | TEXT[] |
+| rural_bushels | rural.bushels | number | DOUBLE PRECISION |
+| rural_acre | rural.acre | number | DOUBLE PRECISION |
+| rural_pasture | rural.pasture | string | TEXT |
+| rural_mechanized | rural.mechanized | string | TEXT |
+| rural_reserve | rural.reserve | number | DOUBLE PRECISION |
+| rural_pigsty | rural.pigsty | integer | INTEGER |
+| rural_aviary | rural.aviary | integer | INTEGER |
+| rural_weir | rural.weir | integer | INTEGER |
+| rural_wood_house | rural.woodHouse | integer | INTEGER |
+| rural_brick_house | rural.brickHouse | integer | INTEGER |
+| rural_mixed_house | rural.mixedHouse | integer | INTEGER |
+
+### Campos personalizados
+
+| Campo normalizado | Fonte SI9 | Tipo | SQL |
+|---|---|---|---|
+| fields | fields[] | array {field, value} | JSONB |
+
+**Limitação:** O campo `fields` é JSONB com objetos aninhados `{field, value}`. NÃO é filtrável via facets/busca no sistema genérico de listagem. Serve apenas para:
+- Exibição na página do imóvel (renderizar os campos extras)
+- Busca textual via FTS (se incluído no fts_vector, os textos são indexados)
+- NÃO suporta facet tipo "mostre todos que têm campo X" sem query JSONB customizada
+
+---
+
+## 4. SITUAÇÕES DO SITE — O QUE O SI9 CONSEGUE RESOLVER
+
+### Badges no card
+| Badge | Disponível? | Como resolver |
+|---|---|---|
+| Lançamento | SIM | `features.release` (boolean, dentro do array features) |
+| Exclusivo | NÃO | Campo personalizado ou não exibir |
+| Permuta | SIM | `destination_exchange` |
+| Financiamento | NÃO | Campo personalizado ou não exibir |
+| MCMV | SIM | `website_mcmv` |
+| Mobiliado | SIM | Dentro do array `features` ("Mobiliado") |
+| Destaque | SIM | Campo base `destaque` |
+| Condomínio fechado | SIM | Dentro do array `features` ("Condomínio") |
+
+### Tarjas (imóvel indisponível)
+| Tarja | Como resolver |
+|---|---|
+| Vendido | `general_data_situation = "SOLD"` |
+| Alugado | `general_data_situation = "RENTED"` |
+| Reservado | `general_data_situation = "RESERVED"` |
+
+Enum completo: AVALIABLE, INACTIVE, RENTED, RESERVED, SOLD, INVOICE, TODOCUMENT, DELETE, TERMINATION, RENOVATION
+
+### Flags de layout
+| Flag | Como resolver |
+|---|---|
+| Tem vídeo | `videos` não vazio |
+| Tem tour 360 | `virtual_tours` não vazio |
+| Geo exato | `lat` e `lng` preenchidos |
+| Geo aproximado | Campo personalizado "Geolocalização aproximada" (sem valor) nos fields |
+| Street View | Campo personalizado "permite-streetview" nos fields (tag) |
+| Solicitar vídeo | `videos` vazio + tag "solicite-video" nos fields |
+| Solicitar tour | `virtual_tours` vazio + tag "solicite-tour" nos fields |
+| Solicitar endereço | Tag "solicite-endereco" nos fields |
+
+### Filtros de busca sugeridos (16 campos)
+
+A busca deve usar campos inteligentes que agrupam múltiplos sub-campos em modais ou menus. Isso mantém a interface limpa (~16 filtros visíveis) enquanto dá acesso a 50+ opções internas. A implementação vai precisar de componentes de filtro especiais tipo "multiselect com grupos internos" ou "modal de checkboxes agrupados".
+
+| # | Filtro | Campo(s) | Tipo | Observação |
+|---|---|---|---|---|
+| 1 | Operação | operacao | multiselect | venda, locação, temporada |
+| 2 | Tipo | tipo | select | Apartamento, Casa, Terreno, etc. |
+| 3 | Cidade | endereco_cidade | multiselect | — |
+| 4 | Bairro | endereco_bairro | multiselect | parent: cidade |
+| 5 | Condomínio | condominio_nome | multiselect | — |
+| 6 | Valor | valor_venda / valor_locacao | range | Adapta conforme operação selecionada |
+| 7 | Dormitórios | dormitorios | range | 1-5+ |
+| 8 | Suítes | suites | range | 1-5+ |
+| 9 | Banheiros | banheiros | range | 1-5+ |
+| 10 | Vagas | vagas_garagem | range | 1-5+ |
+| 11 | Área | area_total / area_privativa | range | Usa o que estiver disponível |
+| 12 | Características | features + security + recreation + rural | **modal agrupado** | 4 grupos internos de checkboxes: Características, Segurança, Lazer, Rural. Cada grupo mostra os itens do respectivo array |
+| 13 | Situação comercial | destaque + website_mcmv + destination_exchange + website_super_highlight + general_data_situation | **modal agrupado** | Checkboxes + select de situação. Agrupa tudo que é decisão comercial/legal num único campo |
+| 14 | Mídia | (computado: tem_video, tem_tour) | multiselect | "Possui vídeo", "Possui tour 360" — derivados da existência de videos[] e virtual_tours[] |
+| 15 | Campos extras | fields | multiselect | Itens dos campos personalizados da imobiliária. Permite buscar por tags e características customizadas |
+| 16 | Busca textual | fts | fulltext | Busca livre em título, descrição, endereço, tipo, etc. |
+
+### Campos para full-text search
+Campos recomendados para indexação de busca textual:
+- title, description, reference
+- endereco_cidade, endereco_bairro, endereco_logradouro, endereco_numero, endereco_complemento, endereco_referencia, endereco_zona, endereco_estado, endereco_cep
+- tipo, condominio_nome, corretor_nome
+- general_data_situation
+- features (array), security (array), recreation (array)
+- recreation_position_sun, recreation_position_court
+- features_floor, features_roof, features_ceiling, features_pavement
+
+---
+
+## 5. TRANSFORMAÇÕES RECOMENDADAS
+
+### Subtipo
+O SI9 não tem subtipo. Pode ser gerado a partir do `tipo` com regras de split:
+```
+Casa → tipo: "Casa", subtipo: null
+Sobrado → tipo: "Casa", subtipo: "Sobrado"
+Apartamento → tipo: "Apartamento", subtipo: null
+Edifício/Prédio → tipo: "Apartamento", subtipo: "Edifício/Prédio"
+Terreno Comercial → tipo: "Terreno", subtipo: "Terreno Comercial"
+```
+
+### Valor por m²
+Pode ser calculado: `(valor_venda || valor_locacao) / (area_total || area_privativa)`. Arredondar 2 casas.
+
+### Campos personalizados como flags de layout
+O SI9 tem `fields[]` (chave-valor). Como a API não expõe campos nativos pra controlar certas funcionalidades do site (street view, solicitar vídeo, etc.), os campos customizados servem como flags.
+
+**Campos reconhecidos pelo conversor:**
+- `"Corretor"` (com valor) → alimenta `corretor_nome` (legado — agora vem do broker nativo)
+- `"Corretor ID"` (com valor) → alimenta `corretor_key` (legado — agora vem do broker nativo)
+- `"Geolocalização aproximada"` (sem valor) → ativa geo aproximado
+
+**Campos customizados usados como flags de layout:**
+- `"permite-streetview"` (sem valor) → habilita Street View na página do imóvel
+- `"solicite-video"` (sem valor) → mostra botão "Solicite Vídeo" quando imóvel não tem vídeo
+- `"solicite-tour"` (sem valor) → mostra botão "Solicite Tour" quando imóvel não tem tour
+- `"solicite-endereco"` (sem valor) → mostra botão "Solicitar Endereço" quando não tem geo exato
+
+**Regra:** Campos sem valor = flag ativa. A existência do campo já é suficiente pra ativar a funcionalidade. Campos com valor = exibidos como características extras na página.
+
+---
+
+## 6. MAPEAMENTO DE LABELS PARA EXIBIÇÃO
+
+Muitos campos do SI9 usam enums em inglês. Qualquer site que exiba esses valores pro usuário precisa traduzir pra português.
+
+### Situação do imóvel → tarjas / stripes / indicadores visuais
+
+O campo `general_data_situation` indica o estado do imóvel. Tradução recomendada:
+
+| Valor da API | Label PT-BR | Uso visual recomendado |
+|---|---|---|
+| SOLD | Vendido | Tarja diagonal sobre o card/imagem |
+| RENTED | Alugado | Tarja diagonal sobre o card/imagem |
+| RESERVED | Reservado | Tarja diagonal sobre o card/imagem |
+| INVOICE | Em faturamento | Tarja ou badge |
+| RENOVATION | Em reforma | Tarja ou badge |
+| AVALIABLE | — | Não exibir (é o estado normal) |
+| INACTIVE | — | Não exibir (imóvel oculto) |
+| TODOCUMENT | — | Não exibir |
+| DELETE | — | Não exibir |
+| TERMINATION | — | Não exibir |
+
+### Enums que precisam de tradução
+
+| Campo | Valor API → Label PT-BR |
+|---|---|
+| recreation_heating | GAS → "Gás", SOLAR → "Solar", ELETRIC → "Elétrico" |
+| recreation_position_sun | NORTH → "Norte", SOUTH → "Sul", EAST → "Leste", WEST → "Oeste" |
+| recreation_position_court | MIDDLE_COURT → "Meio de quadra", CORNER → "Esquina", SUB_CORNER → "Sub-esquina" |
+| features_pavement | COBBLESTONE → "Paralelepípedo", ASPHALT → "Asfalto", GRAVEL → "Cascalho" |
+
+### Campos que JÁ vêm traduzidos (sem necessidade de mapear)
+
+Os arrays `features`, `security`, `recreation`, `rural` já contêm labels em PT-BR direto do conversor. Exemplo: `features: ["Churrasqueira", "Elevador", "Mobiliado"]`.
+
+### Regra geral
+
+| Tipo de campo | Precisa traduzir? |
+|---|---|
+| Enum em inglês (string) | SIM — sempre criar mapa de tradução |
+| Array de labels (string[]) | NÃO — já vem traduzido do conversor |
+| Boolean | NÃO |
+| Number | NÃO |
+
+---
+
+## 7. PRESET DE EXIBIÇÃO RECOMENDADO
+
+Organização sugerida de como apresentar os dados deste CRM em interfaces de listagem e detalhe. Agnóstico de tecnologia — aplicável a qualquer site ou app.
+
+### Card de listagem (resumo do imóvel)
+
+**Tarjas de indisponibilidade** (indicador visual sobre a imagem):
+- `general_data_situation`: SOLD → "Vendido", RENTED → "Alugado", RESERVED → "Reservado", INVOICE → "Em faturamento", RENOVATION → "Em reforma"
+- Não exibir tarja pra AVALIABLE, INACTIVE, TODOCUMENT, DELETE, TERMINATION
+
+**Badges de destaque** (labels sobre a imagem, raramente mais de 2-3 aparecem ao mesmo tempo):
+- `website_mcmv` → "MCMV"
+- `destination_exchange` → "Permuta"
+- `website_super_highlight` → "Super Destaque"
+- Opcionais (dentro do array features): "Mobiliado", "Condomínio", "Alto padrão"
+
+**Atributos principais com ícone** (resumo da ficha):
+- dormitorios, suites, banheiros, vagas_garagem, area_privativa, area_total
+
+### Página de detalhe — Ficha do imóvel
+
+**Seção 1: Principal (ficha técnica)**
+- Contadores: dormitorios, suites, banheiros, vagas_garagem, features_room (salas), features_kitchen (cozinhas), features_closet (closets), features_balcony (varandas), features_ar_condicionado, features_toilet (lavabos)
+- Áreas: area_total, area_privativa, area_util
+- Classificação: tipo, operacao
+- Situação comercial: general_data_situation, website_mcmv, destination_exchange
+
+**Seção 2: Características e acabamentos** (juntos — acabamentos são poucos campos)
+- Array `features[]` expandido como checkmarks (Churrasqueira, Elevador, etc.)
+- Acabamentos: features_floor (piso), features_roof (teto), features_ceiling (forro), features_paving (pavimentação), features_pavement (calçamento)
+
+**Seção 3: Segurança**
+- Array `security[]` expandido como checkmarks (Interfone, Murado, Portão, etc.)
+
+**Seção 4: Lazer** (incluir enums junto com booleans)
+- Array `recreation[]` expandido como checkmarks (Piscina, Academia, etc.)
+- Enums: recreation_heating (aquecimento), recreation_position_sun (posição solar), recreation_position_court (posição quadra)
+
+**Seção 5: Dimensões**
+- dimensions_building_area, dimensions_land_area, dimensions_internal_area, dimensions_registered_area, dimensions_common_area, dimensions_garage_area
+- dimensions_front_size, dimensions_funds_size, dimensions_left_size, dimensions_right_size
+
+**Seção 6: Localização complementar**
+- location_apartment, location_block, location_floor, location_quatrain, location_lot
+
+**Seção 7: Rural** (só exibir se imóvel tiver dados rurais)
+- Array `rural[]` expandido como checkmarks
+- Numéricos: rural_bushels, rural_acre, rural_pasture, rural_mechanized, rural_reserve, rural_pigsty, rural_aviary, rural_weir, rural_wood_house, rural_brick_house, rural_mixed_house
+
+**Seção 8: Campos extras** (fields[] customizados)
+- Exibir como lista key-value os campos que não foram consumidos pelo conversor
+
+### Página de detalhe — Caixa de valores (lateral)
+
+**Bloco Venda** (se operação inclui venda):
+- Valor principal: valor_venda
+- Flags: website_mcmv, destination_exchange
+
+**Bloco Locação** (se operação inclui locação):
+- Valor principal: valor_locacao
+- Taxas: valor_condominio, valor_iptu, values_trash_fee, values_disaster_fee
+- Outros: values_discount_value, values_fci_value, values_assigned_value
+
+---
+
+## 8. ENUMS E VALORES POSSÍVEIS (referência completa)
+
+### generalData.situation
+AVALIABLE (disponível), INACTIVE (inativo), RENTED (alugado), RESERVED (reservado), SOLD (vendido), INVOICE (em faturamento), TODOCUMENT (em documentação), DELETE (excluído), TERMINATION (rescisão), RENOVATION (em reforma)
+
+**Nota:** "AVALIABLE" é typo oficial da API (falta um L).
+
+### generalData.category.name (tipos encontrados nos dados)
+Apartamento, Casa, Terreno, Sobrado, Sala Comercial, Chácara, Ponto Comercial, Terreno Comercial, Edifício/Prédio, Rural, Sítio
+
+### recreation.heating
+GAS, SOLAR, ELETRIC
+
+### recreation.positionSun
+NORTH, SOUTH, EAST, WEST
+
+### recreation.positionCourt
+MIDDLE_COURT, CORNER, SUB_CORNER
+
+### features.pavement
+COBBLESTONE (paralelepípedo), ASPHALT (asfalto), GRAVEL (cascalho)
+
+---
+
+## 7. ORIENTAÇÕES PARA BANCO DE DADOS
+
+Diretrizes genéricas de como implementar os campos extras deste CRM em qualquer banco de dados relacional.
+
+### Tipos de coluna recomendados
+
+| Tipo do campo | Tipo SQL recomendado | Exemplo |
+|---|---|---|
+| string | TEXT | general_data_situation, features_floor |
+| string (curta, enum) | VARCHAR(50) | recreation_heating, features_pavement |
+| number (monetário) | DOUBLE PRECISION | values_discount_value, values_trash_fee |
+| number (inteiro/contagem) | INTEGER | features_room, rural_pigsty |
+| number (medida/área) | DOUBLE PRECISION | dimensions_building_area, dimensions_front_size |
+| boolean | BOOLEAN | website_mcmv, destination_exchange |
+| string[] (array de labels) | TEXT[] | features, security, recreation, rural |
+| object (chave-valor) | JSONB | fields |
+
+### Índices recomendados
+
+| Campo | Tipo de índice | Motivo |
+|---|---|---|
+| general_data_situation | B-tree | Filtro frequente por situação (SOLD, RENTED, etc.) |
+| features | GIN | Busca por itens dentro do array (ex: WHERE 'Piscina' = ANY(features)) |
+| security | GIN | Idem |
+| recreation | GIN | Idem |
+| rural | GIN | Idem |
+| website_mcmv | B-tree | Filtro boolean |
+| destination_exchange | B-tree | Filtro boolean |
+| dimensions_building_area | B-tree | Range queries |
+| dimensions_land_area | B-tree | Range queries |
+
+### Campos recomendados para Full-Text Search
+
+Além dos campos base (title, description, endereço, tipo), incluir estes extras do CRM no índice de busca textual:
+
+```
+general_data_situation
+features (array → converter cada item pra texto)
+security (array)
+recreation (array)
+rural (array)
+condominio_nome (já no base)
+corretor_nome (já no base)
+recreation_position_sun
+recreation_position_court
+features_floor
+features_roof
+features_ceiling
+features_pavement
+recreation_heating
+location_apartment
+location_block
+location_floor
+```
+
+### Campos que NÃO precisam de índice
+
+Campos raramente usados em filtros ou com baixa cardinalidade:
+- general_data_board (placa)
+- values_fci_value, values_assigned_value, values_disaster_fee (quase sempre 0)
+- dimensions_internal_area, dimensions_registered_area, dimensions_common_area, dimensions_garage_area (quase sempre null)
+- rural_* (só relevante pra imóveis rurais, minoria)
+- location_quatrain, location_lot (raramente preenchidos)
+
+### Campos computados sugeridos (gerar no backend antes de salvar)
+
+| Campo computado | Fórmula | Tipo SQL |
+|---|---|---|
+| valor_m2 | (valor_venda \|\| valor_locacao) / (area_total \|\| area_privativa) | DECIMAL(10,2) |
+| subtipo | Derivado de `tipo` com regras de split | TEXT |
+| endereco_completo | Concatenação formatada dos campos de endereço | TEXT |
+| seo_slug | Slug gerado do título + referência | VARCHAR(255) |
+| thumbnails | Extraído de images[].full (primeiras N URLs) | TEXT[] ou JSONB |
+
+---
+
+## 8. OBSERVAÇÕES TÉCNICAS
+
+- Valores monetários em REAIS — nunca dividir por 100
+- IPTU é valor ANUAL
+- lat/lng vêm como STRING — converter pra number
+- `recreation.playgroud` tem typo (falta o "n") — manter como vem
+- Token expira em 1h (3599s) — suporta refresh_token
+- Sem paginação na API — GET /property retorna tudo de uma vez
+- Imagens têm campo `displaySite` (boolean) — filtrar só as que são true
+- `pic360` nas imagens é boolean (indica foto panorâmica), não URL de tour
+- Endpoint `GET /user` lista corretores mas SEM vínculo ao imóvel

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@horizon-integrations/si9-crm",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "description": "Integração da Imobland Horizon com a SI9 CRM",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
-    "examples"
+    "examples",
+    "FICHA_TECNICA_INTEGRACAO.md"
   ],
   "scripts": {
     "build": "tsup",