Campos Customizados e Dados Estruturados

Esta documentação explica como usar diferentes tipos de campos na API do Garagem: marketing attribution, preferências de busca, e campos customizados.

📊 Marketing Attribution

Os campos de marketing attribution são processados pelo sistema de rastreamento de atribuição e devem ser enviados no nível superior da requisição (não dentro de custom).

Campos Disponíveis

{
  "utmSource": "google",
  "utmMedium": "cpc",
  "utmCampaign": "apartamentos-zona-sul",
  "source": "Google Ads",
  "campaign": "Campanha Verão 2024",
  "marketingChannelInstanceId": "uuid-do-canal-marketing"
}

Descrição dos Campos

utmSource - Fonte do tráfego (ex: “google”, “facebook”, “direct”)
utmMedium - Meio de marketing (ex: “cpc”, “organic”, “social”, “email”)
utmCampaign - Nome da campanha (ex: “apartamentos-zona-sul”, “lancamento-2024”)
source - Origem legível do lead (ex: “Google Ads”, “Facebook Ads”, “Site”)
campaign - Nome legível da campanha (ex: “Campanha Verão 2024”)
marketingChannelInstanceId - ID do canal de marketing configurado no sistema

Exemplo de Uso

curl -X POST https://app.garagem.ai/api/v1/crm/deals \
  -H "Authorization: Bearer sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Lead do Google Ads",
    "dealType": "rental",
    "stage": "lead",
    "status": "open",
    "currency": "BRL",
    "utmSource": "google",
    "utmMedium": "cpc",
    "utmCampaign": "apartamentos-zona-sul",
    "source": "Google Ads",
    "campaign": "Apartamentos Zona Sul",
    "marketingChannelInstanceId": "uuid-do-canal-marketing",
    "contacts": [
      {
        "name": "João Silva",
        "email": "[email protected]",
        "phone": "+5511999999999",
        "role": "buyer"
      }
    ]
  }'

Parâmetros UTM Adicionais

Para parâmetros UTM adicionais (utm_term, utm_content), você pode armazená-los em custom:

{
  "custom": {
    "utm_term": "apartamento 2 quartos",
    "utm_content": "ad-variation-a",
    "landingPage": "/imoveis/apartamento-123",
    "referrer": "https://www.google.com"
  }
}

🔍 Preferências de Busca (Search Preferences)

Para negociações (deals), use estes campos específicos em custom para configurar preferências de busca. Estes campos são usados pelo sistema de recomendação de imóveis.

Campos Disponíveis

{
  "custom": {
    "maxPrice": 4000,
    "minPrice": 2000,
    "locations": ["Zona Sul", "Copacabana"],
    "propertyTypes": ["apartment", "house"],
    "bedrooms": 2,
    "bathrooms": 1,
    "suites": 1,
    "minArea": 60,
    "maxArea": 120,
    "searchPolygon": {
      /* GeoJSON polygon */
    },
    "geographicAreaId": "uuid-da-area-geografica"
  }
}

Descrição dos Campos

maxPrice - Preço máximo (número)
minPrice - Preço mínimo (número)
locations - Array de localizações preferidas (ex: [“Zona Sul”, “Copacabana”])
propertyTypes - Array de tipos de imóvel (ex: [“apartment”, “house”])
bedrooms - Número mínimo de quartos (número)
bathrooms - Número mínimo de banheiros (número)
suites - Número mínimo de suítes (número)
minArea - Área mínima em m² (número)
maxArea - Área máxima em m² (número)
searchPolygon - Polígono de busca em formato GeoJSON (objeto)
geographicAreaId - ID da área geográfica configurada no sistema (UUID)

Exemplo de Uso

curl -X POST https://app.garagem.ai/api/v1/crm/deals \
  -H "Authorization: Bearer sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Cliente buscando apartamento",
    "dealType": "rental",
    "stage": "lead",
    "status": "open",
    "currency": "BRL",
    "contacts": [
      {
        "name": "Maria Santos",
        "email": "[email protected]",
        "phone": "+5511999999999",
        "role": "buyer"
      }
    ],
    "custom": {
      "maxPrice": 3500,
      "minPrice": 2500,
      "locations": ["Zona Sul", "Copacabana", "Ipanema"],
      "propertyTypes": ["apartment"],
      "bedrooms": 2,
      "bathrooms": 1,
      "minArea": 60,
      "maxArea": 100
    }
  }'

Importante:

Estes campos são usados pelo sistema de recomendação automática de imóveis
Use os nomes exatos acima - não use variações como orçamento, quartos, banheiros
O sistema irá recomendar imóveis que correspondam a estas preferências

🏷️ Campos Customizados (Custom Fields)

O campo custom permite armazenar qualquer dado adicional que você precise, além dos campos estruturados acima.

Quando Usar

Use campos customizados para:

Dados específicos do seu negócio
Metadados adicionais
Informações que não se encaixam nos campos estruturados
Dados temporários ou experimentais

Estrutura

O campo custom é um objeto JSON flexível:

{
  "custom": {
    "campo1": "valor1",
    "campo2": 123,
    "campo3": true,
    "campo4": ["item1", "item2"],
    "campo5": {
      "subcampo": "valor"
    }
  }
}

Exemplos para Negociações (Deals)

{
  "custom": {
    "observacoes": "Cliente interessado em imóveis próximos ao metrô",
    "aceita_financiamento": true,
    "prazo_mudanca": "2024-06-01",
    "tipo_contrato_preferido": "temporada",
    "pet_friendly": true,
    "fumante": false,
    "observacoes_especiais": "Necessita vaga de garagem coberta"
  }
}

Exemplos para Anúncios (Listings)

{
  "custom": {
    "descricao_detalhada": "Apartamento reformado com vista para o mar",
    "mobiliado": true,
    "aceita_pet": true,
    "aceita_financiamento": true,
    "destaque": true,
    "destaque_ate": "2024-12-31",
    "observacoes_internas": "Proprietário prefere inquilino sem filhos",
    "tags": ["reformado", "vista-mar", "mobiliado"],
    "metadados": {
      "origem_importacao": "grupozap",
      "id_externo": "12345",
      "ultima_sincronizacao": "2024-01-15T10:30:00Z"
    }
  }
}

Filtrar por Campos Customizados

Use o parâmetro customFilters na listagem para filtrar por campos dentro de custom:

# Filtrar por campo customizado
curl -X GET "https://app.garagem.ai/api/v1/crm/deals?customFilters=%7B%22aceita_financiamento%22%3Atrue%7D" \
  -H "Authorization: Bearer sua_api_key"

# Filtrar por múltiplos campos
curl -X GET "https://app.garagem.ai/api/v1/crm/deals?customFilters=%7B%22pet_friendly%22%3Atrue%2C%22mobiliado%22%3Atrue%7D" \
  -H "Authorization: Bearer sua_api_key"

Nota: O customFilters deve ser uma string JSON codificada em URL. Exemplo:

JSON: {"aceita_financiamento":true}
URL encoded: %7B%22aceita_financiamento%22%3Atrue%7D

📋 Listings - Campos Customizados

Para anúncios (listings), você pode usar campos customizados para armazenar informações adicionais específicas do anúncio.

Campos Disponíveis em Listings

Além do campo custom, listings também suportam:

typeSpecificData - Dados específicos do tipo (rental/sale)
acceptanceCriteria - Critérios de aceitação do proprietário
marketingChannelInstanceId - ID do canal de marketing

Exemplo Completo de Listing

curl -X POST https://app.garagem.ai/api/v1/real-estate/properties \
  -H "Authorization: Bearer sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "property": {
      "title": "Apartamento 2 quartos - Copacabana",
      "type": "apartment",
      "bedrooms": 2,
      "bathrooms": 1,
      "totalArea": "75"
    },
    "location": {
      "address": "Rua Example, 123",
      "neighborhood": "Copacabana",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "zipCode": "22020-000"
    },
    "listings": [
      {
        "title": "Apartamento 2 quartos para alugar",
        "type": "rental",
        "price": "3500.00",
        "currency": "BRL",
        "stage": "active",
        "marketingChannelInstanceId": "uuid-do-canal-marketing",
        "custom": {
          "mobiliado": true,
          "aceita_pet": true,
          "destaque": true,
          "tags": ["reformado", "vista-mar"],
          "observacoes_internas": "Proprietário prefere inquilino sem filhos"
        },
        "typeSpecificData": {
          "deposit": 7000,
          "iptu": 200,
          "condominiumFee": 500
        },
        "acceptanceCriteria": {
          "minIncome": 10500,
          "requiresGuarantor": true,
          "petAllowed": true
        }
      }
    ]
  }'

Campos em `typeSpecificData` (Rental)

{
  "typeSpecificData": {
    "deposit": 7000,
    "iptu": 200,
    "condominiumFee": 500,
    "rentalPeriod": "12 meses",
    "furnished": true
  }
}

Campos em `typeSpecificData` (Sale)

{
  "typeSpecificData": {
    "downPayment": 85000,
    "financingAllowed": true,
    "iptu": 500,
    "condominiumFee": 800
  }
}

Campos em `acceptanceCriteria`

{
  "acceptanceCriteria": {
    "minIncome": 10500,
    "requiresGuarantor": true,
    "petAllowed": true,
    "smokingAllowed": false,
    "maxOccupants": 3
  }
}

📝 Exemplo Completo Combinado

Exemplo de criação de negociação com todos os tipos de campos:

{
  "title": "Lead do Site - João Silva",
  "dealType": "rental",
  "stage": "lead",
  "status": "open",
  "currency": "BRL",
  "contacts": [
    {
      "name": "João Silva",
      "email": "[email protected]",
      "phone": "+5511999999999",
      "role": "buyer"
    }
  ],
  "marketingChannelInstanceId": "uuid-do-canal-marketing",
  "utmSource": "google",
  "utmMedium": "cpc",
  "utmCampaign": "verao-2024",
  "source": "Google Ads",
  "campaign": "Campanha Verão 2024",
  "custom": {
    "maxPrice": 4000,
    "minPrice": 2000,
    "locations": ["Zona Sul", "Copacabana"],
    "propertyTypes": ["apartment"],
    "bedrooms": 2,
    "bathrooms": 1,
    "utm_term": "apartamento copacabana",
    "utm_content": "ad-variation-a",
    "landingPage": "/imoveis/apartamento-123",
    "observacoes": "Cliente interessado em imóveis próximos ao metrô",
    "aceita_financiamento": true,
    "pet_friendly": true
  }
}

🔑 Resumo

Tipo	Onde Usar	Campos Principais
Marketing Attribution	Nível superior	`utmSource`, `utmMedium`, `utmCampaign`, `source`, `campaign`
Search Preferences	`custom` (deals)	`maxPrice`, `minPrice`, `locations`, `propertyTypes`, `bedrooms`, `bathrooms`
Custom Fields	`custom`	Qualquer campo personalizado`
Listing Specific	`typeSpecificData`, `acceptanceCriteria`	`deposit`, `iptu`, `minIncome`, etc.

Lembre-se:

Marketing attribution vai no nível superior
Search preferences vão em custom (apenas deals)
Custom fields vão em custom (qualquer entidade)
Listings têm campos adicionais específicos

Campos Customizados e Dados Estruturados

📊 Marketing Attribution

Campos Disponíveis

Descrição dos Campos

Exemplo de Uso

Parâmetros UTM Adicionais

🔍 Preferências de Busca (Search Preferences)

Campos Disponíveis

Descrição dos Campos

Exemplo de Uso

🏷️ Campos Customizados (Custom Fields)

Quando Usar

Estrutura

Exemplos para Negociações (Deals)

Exemplos para Anúncios (Listings)

Filtrar por Campos Customizados

📋 Listings - Campos Customizados

Campos Disponíveis em Listings

Exemplo Completo de Listing

Campos em typeSpecificData (Rental)

Campos em typeSpecificData (Sale)

Campos em acceptanceCriteria

📝 Exemplo Completo Combinado

🔑 Resumo

Campos em `typeSpecificData` (Rental)

Campos em `typeSpecificData` (Sale)

Campos em `acceptanceCriteria`