Compartilhamento de Imóveis

Esta seção documenta os endpoints e configurações para compartilhamento de anúncios de imóveis, seleções e relatórios.

---

📖 Visão Geral

O sistema de compartilhamento do Garagem permite criar links públicos para:

• Anúncios individuais (listing)
• Seleções de imóveis (shortlist)
• Relatórios para proprietários (seller_report)
• Roteiros de visita (visit_itinerary)

🔗 Endpoint de Resolução de Share

📖 Documentação completa do endpoint: Veja Sites API - Links de Compartilhamento para detalhes técnicos completos incluindo exemplos de código e integração.

Resumo do Endpoint

GET /api/sites/share/{token}
POST /api/sites/share/{token}  (para links protegidos por senha)

Respostas de Erro:

Status	Código	Descrição
401	password_required	Link protegido - senha necessária
403	password_invalid	Senha incorreta
404	not_found	Token não encontrado ou inativo
410	expired	Link expirado

---

🔒 Visibilidade de Campos

O sistema permite controlar quais informações são exibidas nos links de compartilhamento através da configuração sharingConfig.fieldVisibility.

Nota: Esta configuração é diferente do campo visibility do anúncio. O campo visibility controla se o anúncio aparece em buscas públicas (public/private). A configuração fieldVisibility controla quais campos são exibidos em links de compartilhamento. Veja Anúncios para mais detalhes.

Níveis de Visibilidade de Endereço

Valor	Campos Visíveis	Campos Ocultos
full	Rua, número, bairro, cidade, estado, CEP	Nenhum
neighborhood_only	Bairro, cidade, estado	Rua, número, CEP
city_only	Cidade, estado	Rua, número, bairro, CEP
hidden	Nenhum	Todos os campos de endereço

Visibilidade de Coordenadas/Mapa

Valor	Comportamento
exact	Coordenadas exatas (latitude/longitude originais)
approximate	Coordenadas randomizadas (~500m de raio do ponto original)
hidden	Coordenadas não são retornadas

Visibilidade de Informações Financeiras

Valor	Comportamento
visible	Condomínio (condoFee) e IPTU (propertyTax) visíveis
hidden	Campos financeiros ocultados

Visibilidade de Preço

Valor	Comportamento
inherit	Usa configuração priceVisibility do próprio anúncio
hidden	Força ocultação do preço em todos os links compartilhados

Nota: A configuração hidden sobrescreve a configuração individual do anúncio.

Visibilidade do Código do Anúncio

Valor	Comportamento
visible	Código do anúncio é exibido
hidden	Código do anúncio é ocultado

Simulador de financiamento no link

O simulador de financiamento nos links de imóvel à venda em *.garagem.link é controlado por sharingConfig.showFinancialSimulator, em Configurações → Compartilhamento. Não é preciso publicar um site.

Valor	Comportamento
omitido / true	Padrão. Links de venda no chrome mínimo mostram o simulador (bloco vazio, sem template de site)
false	Oculta o simulador em *.garagem.link, inclusive se o template publicado do site o exibiria

Nota: fieldVisibility.financials controla condomínio e IPTU, não o simulador. Links abertos no domínio do site publicado continuam seguindo o template do editor (página do imóvel).

Exemplo de Configuração

{
  "sharingConfig": {
    "showFinancialSimulator": false,
    "fieldVisibility": {
      "address": "neighborhood_only",
      "coordinates": "approximate",
      "financials": "hidden",
      "agentInfo": "visible",
      "listingCode": "hidden",
      "price": "inherit"
    }
  }
}

---

🚫 Restrições de Compartilhamento

Restrições por Etapa (Stage)

Configure quais etapas do workflow não podem ter links de compartilhamento ativos ou criados.

Configuração	Descrição
hideSharesForStages	Links existentes retornam 404 quando o anúncio está nessas etapas
preventCreationForStages	Não permite criar novos links para anúncios nessas etapas
autoHideTerminalStages	Oculta automaticamente links de anúncios em etapas terminais (ex: “closed”)

Restrições por Status

Configuração	Descrição
preventCreationForStatuses	Não permite criar novos links para anúncios com esses status

Exemplo de Configuração

{
  "sharingConfig": {
    "restrictions": {
      "hideSharesForStages": ["closed"],
      "preventCreationForStages": [],
      "preventCreationForStatuses": ["vendido", "alugado"],
      "autoHideTerminalStages": true
    }
  }
}

Comportamento Padrão: Quando autoHideTerminalStages está ativo (padrão: true), links de anúncios em etapas terminais (como “closed”) automaticamente retornam 404.

---

🌐 Domínios Personalizados

O Garagem suporta três modos de domínio para links de compartilhamento:

1. Domínio Automático (auto)

{
  "defaultShareDomain": {
    "type": "auto"
  }
}

URL gerada: https://{org-slug}.garagem.link/p/{token}

2. Domínio do Site (site)

Usa o domínio de um site configurado no Garagem.

{
  "defaultShareDomain": {
    "type": "site",
    "siteId": "uuid-do-site"
  }
}

URL gerada: https://www.seusite.com.br/p/{token}

3. Domínio Personalizado (custom)

Modo Proxy

O tenant configura seu domínio para fazer proxy das requisições para a API do Garagem.

{
  "defaultShareDomain": {
    "type": "custom",
    "custom": {
      "mode": "proxy",
      "domain": "compartilhar.seusite.com.br",
      "pathTemplate": "/p/{token}"
    }
  }
}

Requisitos:

• Configurar DNS apontando para o servidor do tenant
• Configurar reverse proxy (nginx, cloudflare, etc.) para encaminhar requisições para https://app.garagem.ai/api/sites/share/{token}

Modo API

O tenant consome a API do Garagem diretamente e renderiza o conteúdo em seu próprio site/aplicativo.

{
  "defaultShareDomain": {
    "type": "custom",
    "custom": {
      "mode": "api",
      "domain": "www.seusite.com.br",
      "pathTemplate": "/imovel/{token}"
    }
  }
}

Como Funciona:

1. Tenant gera link: https://www.seusite.com.br/imovel/abc123
2. Aplicativo do tenant recebe a requisição
3. Aplicativo chama: GET https://app.garagem.ai/api/sites/share/abc123
4. Aplicativo renderiza os dados retornados

Nota: O endpoint /api/sites/share/{token} já suporta CORS, permitindo chamadas de qualquer origem.

---

📊 Tipos de Entidade

Listing (Anúncio Individual)

{
  "type": "listing",
  "listing": { ... },
  "property": { ... },
  "medias": [ ... ]
}

Shortlist (Seleção de Imóveis)

{
  "type": "shortlist",
  "shortlist": {
    "id": "uuid",
    "name": "Seleção para João",
    "description": "Opções de apartamento 2 quartos"
  },
  "listings": [ ... ],
  "listingCount": 5
}

Seller Report (Relatório do Proprietário)

{
  "type": "seller_report",
  "listing": { ... },
  "property": { ... },
  "medias": [ ... ],
  "stats": {
    "views": 150,
    "leads": 12,
    "daysOnMarket": 45
  }
}

Visit Itinerary (Roteiro de Visita)

{
  "type": "visit_itinerary",
  "itinerary": {
    "id": "uuid",
    "name": "Visitas - Terça 14h",
    "scheduledDate": "2024-01-20T14:00:00Z"
  },
  "stops": [ ... ],
  "meetingPoint": { ... },
  "routeCache": { ... },
  "stopCount": 3
}

Pricing Tool (Calculadora de Preço)

Link permanente por organização (entityId = tenantId, resolvido no servidor — o cliente não envia entityId). Renderizado em /c/{token}.

{
  "type": "pricing_tool",
  "pricingTool": {
    "cities": [{ "code": "sp", "label": "São Paulo", "state": "SP" }]
  }
}

Configuração do tenant (sharingConfig.pricingTool, em Configurações → Compartilhamento): sellerIntentCreates decide o que um lead vendedor produz — "deal" (padrão, só a negociação) ou "deal_and_draft_listing" (negociação + imóvel/anúncio em rascunho vinculado, quando o cliente informar rua, número, CEP e bairro; passa por geocodificação e detecção de duplicados como qualquer rascunho).

Endpoints públicos auxiliares (mesmo token, CORS aberto, rate-limited):

Endpoint	Método	Função
/api/sites/share/{token}/price-estimate	POST	Estimativa AVM pública (ponto + faixa + confiança; sem sinais internos)
/api/sites/share/{token}/neighborhoods?city=&q=	GET	Autocomplete de bairros (nomes canônicos)
/api/sites/share/{token}/pricing-lead	POST	Captura o lead (contato + perfil do imóvel + estimativa exibida) no CRM

---

🔐 Segurança

Links Protegidos por Senha

Para criar um link protegido:

1. Ao criar o share token via tRPC, inclua uma senha
2. Para acessar, faça uma requisição POST com a senha no body

curl -X POST https://app.garagem.ai/api/sites/share/{token} \
  -H "Content-Type: application/json" \
  -d '{"password": "senha123"}'

Expiração de Links

Links podem ter data de expiração configurada. Após a expiração, retornam status 410 (Gone).

Rastreamento de Acessos

O sistema registra acessos aos links compartilhados, permitindo:

• Notificações quando clientes visualizam o link
• Estatísticas de visualização para relatórios
• Análise de engajamento

---

📚 Mais Informações

• Sites API - Documentação completa dos endpoints públicos
• Guia Rápido - Primeiros passos com a API
• Exemplos Práticos - Casos de uso comuns
• Webhooks e Eventos - Receber notificações de eventos