@horizon-integrations/si9-crm

Integracao completa com o CRM SI9 Sistemas para a plataforma Horizon.

🔴 BREAKING — v3.0.0 (2026-05-13): SI9 reescreveu a API. Auth agora é API Key (não mais OAuth2), e a base URL mudou. Veja seção Migração v2 → v3 abaixo. A API antiga (api.si9sistemas.com.br/imobilsi9-api) está descontinuada e retorna 400 "You have to use the new version of this api!".

O que faz

• Baixa imoveis da API SI9 v2 (PropertyDownloader)
• Converte do formato SI9 para o formato Horizon (convertSi9PropertyToHorizon)
• Envia leads para o CRM SI9 (sendLead, sendLeadFromForm)

Instalacao

pnpm add @horizon-integrations/si9-crm

Uso rapido

Converter imoveis (SI9 -> Horizon)

import { fetchAll, convertSi9PropertyToHorizon } from "@horizon-integrations/si9-crm"

// 1. Baixar e converter TODOS os imoveis (em memoria)
const { properties, errors } = await fetchAll({
  credentials: {
    apiKey: process.env.SI9_API_KEY!,
  },
})

// 2. Ou converter manualmente um imovel raw
const horizonProperty = convertSi9PropertyToHorizon(imovelSi9Raw)

v1.4.0+: fetchAll() e getListing() são puros em memória — ideais pra APIs serverless. O legado PropertyDownloader#downloadAll() continua disponível pra scripts locais que gravam JSON em disco.

Enviar leads (forma recomendada v1.3.0+)

import { sendLeadFromForm } from "@horizon-integrations/si9-crm"

const result = await sendLeadFromForm(formData, formMeta, {
  apiKey: process.env.SI9_API_KEY!,
})

// result: { success: true, platform: "si9", leadId: 527 }

O sendLeadFromForm:

• Normaliza campos via adaptGenericLead do lead-core
• Monta observation formatada com buildObservation (mensagem + dados do form + metadados + UTMs)
• Mapeia property_ref -> propertyId, property_operation -> interestedIn
• Trata string[], labels bonitos, papa-tudo automatico
• Qualquer campo novo no formulario vai pra observation sem precisar mexer no pacote

Enviar leads (baixo nivel)

import { sendLead } from "@horizon-integrations/si9-crm"

const result = await sendLead({
  name: "Joao Silva",
  email: "[email protected]",
  phone: "(46) 99999-0001",
  message: "Tenho interesse neste imovel",
  propertyId: 855,
  propertyOperation: "venda",
}, { apiKey: process.env.SI9_API_KEY! })

API SI9 v2

• Base URL: https://apiv2.si9sistemas.com.br/api-prd
• Auth: X-Api-Key: Bearer <token> (API Key tenant-scoped, sem expiração)
• Imoveis: GET /property (suporta filtros como situation=D, lastUpdate=YYYY-MM-DD)
• Lead: POST /lead (upsert por phone/email)
• Docs oficiais: https://apiv2.si9sistemas.com.br/api-prd/integration-guide.md
• Swagger UI: https://apiv2.si9sistemas.com.br/api-prd/docs

Gerar a API Key

Painel SI9 → Configurações → API Keys → criar token com permissões:

• LIST_IMOVEIS — obrigatório (GET /property e GET /property/{id})
• LIST_LEADS — opcional (GET /lead)
• CADASTRAR_LEADS — opcional (writers de lead)

Migração v2 → v3

| Antes (v2.x) | Agora (v3.x) | |---|---| | credentials: { username, password, authorization } | credentials: { apiKey } | | https://api.si9sistemas.com.br/imobilsi9-api | https://apiv2.si9sistemas.com.br/api-prd | | POST /oauth/token + Bearer cacheado | Header X-Api-Key: Bearer <apiKey> direto | | Token TTL 3599s, refresh automático | Sem expiração | | ENV: SI9_USERNAME / SI9_PASSWORD / SI9_AUTHORIZATION | ENV: SI9_API_KEY |

Endpoints públicos (GET /property, GET /property/{id}, POST /lead) mantêm path. Apenas auth e host mudaram.

Documentacao detalhada

• docs/API_REFERENCE.md — Referência completa dos métodos públicos (PropertyDownloader, fetchAll, getListing, converter, sendLead)
• docs/LEAD_SENDER.md — Envio de leads, campos, mapeamento, observation formatada
• docs/FICHA_TECNICA_INTEGRACAO.md — Ficha técnica completa do output Horizon

Dependencias

• @horizon-js/lead-core — Tipagem universal e adapter de leads
• @horizon-js/property-domain-schema — Schema base de imoveis Horizon