Exemplos Práticos

Esta seção contém exemplos práticos de uso da API para casos de uso comuns.

Criar Negociação com Marketing Attribution

Criar uma negociação rastreando origem de marketing:

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",
    "contacts": [
      {
        "name": "João Silva",
        "email": "[email protected]",
        "phone": "+5511999999999",
        "role": "buyer"
      }
    ],
    "marketingChannelInstanceId": "uuid-do-canal-marketing",
    "utmSource": "google",
    "utmMedium": "cpc",
    "utmCampaign": "apartamentos-zona-sul",
    "source": "Google Ads",
    "campaign": "Apartamentos Zona Sul",
    "custom": {
      "utm_term": "apartamento 2 quartos",
      "utm_content": "ad-123",
      "landingPage": "/imoveis/apartamento-123"
    }
  }'

Criar Negociação com Preferências de Busca

Criar uma negociação com preferências de busca para receber recomendações automáticas:

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
    }
  }'

Criar Negociação Completa (Marketing + Preferências + Custom)

Criar uma negociação com todos os tipos de campos:

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 Completo - 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": "apartamentos-zona-sul",
    "source": "Google Ads",
    "campaign": "Apartamentos Zona Sul",
    "custom": {
      "maxPrice": 4000,
      "minPrice": 2000,
      "locations": ["Zona Sul", "Copacabana"],
      "propertyTypes": ["apartment"],
      "bedrooms": 2,
      "bathrooms": 1,
      "utm_term": "apartamento 2 quartos",
      "utm_content": "ad-123",
      "landingPage": "/imoveis/apartamento-123",
      "observacoes": "Cliente interessado em imóveis próximos ao metrô",
      "aceita_financiamento": true,
      "pet_friendly": true
    }
  }'

Filtrar Negociações

Por Canal de Marketing

curl -X GET "https://app.garagem.ai/api/v1/crm/deals?marketingChannelInstanceId=uuid-do-canal&limit=50" \
  -H "Authorization: Bearer sua_api_key"

Por Campos Customizados

# 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 preferências de busca
curl -X GET "https://app.garagem.ai/api/v1/crm/deals?customFilters=%7B%22locations%22%3A%5B%22Zona%20Sul%22%5D%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%22maxPrice%22%3A4000%7D" \
  -H "Authorization: Bearer sua_api_key"

Nota:

• O parâmetro customFilters deve ser uma string JSON codificada em URL
• Use marketingChannelInstanceId para filtrar por canal de marketing
• Campos de marketing attribution são processados pelo sistema e não devem ser filtrados via customFilters

Criar Imóvel com Múltiplos Anúncios

Criar um imóvel completo com anúncios para aluguel e venda, incluindo campos customizados e dados específicos:

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",
      "usableArea": "65"
    },
    "location": {
      "address": "Rua Example, 123",
      "neighborhood": "Copacabana",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "zipCode": "22020-000",
      "latitude": -22.970722,
      "longitude": -43.182365
    },
    "listings": [
      {
        "title": "Apartamento 2 quartos para alugar",
        "type": "rental",
        "price": "3500.00",
        "currency": "BRL",
        "stage": "active",
        "marketingChannelInstanceId": "uuid-do-canal-marketing",
        "custom": {
          "descricao_detalhada": "Apartamento reformado com vista para o mar",
          "mobiliado": true,
          "aceita_pet": true,
          "destaque": true,
          "tags": ["reformado", "vista-mar"]
        },
        "typeSpecificData": {
          "deposit": 7000,
          "iptu": 200,
          "condominiumFee": 500,
          "rentalPeriod": "12 meses",
          "furnished": true
        },
        "acceptanceCriteria": {
          "minIncome": 10500,
          "requiresGuarantor": true,
          "petAllowed": true,
          "smokingAllowed": false
        }
      },
      {
        "title": "Apartamento 2 quartos à venda",
        "type": "sale",
        "price": "450000.00",
        "currency": "BRL",
        "stage": "active",
        "custom": {
          "destaque": true,
          "tags": ["reformado", "vista-mar"],
          "observacoes_internas": "Aceita financiamento"
        },
        "typeSpecificData": {
          "downPayment": 90000,
          "financingAllowed": true,
          "iptu": 500,
          "condominiumFee": 800
        }
      }
    ]
  }'

Criar Tarefa Relacionada a Negociação

Criar uma tarefa para acompanhar uma negociação:

curl -X POST https://app.garagem.ai/api/v1/crm/tasks \
  -H "Authorization: Bearer sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Agendar visita ao imóvel",
    "description": "Cliente interessado em visitar o apartamento",
    "dueDate": "2024-01-20T14:00:00Z",
    "dealId": "uuid-do-deal",
    "stage": "todo",
    "status": "open",
    "custom": {
      "tipo_visita": "presencial",
      "duracao_estimada": 60,
      "observacoes": "Cliente prefere horário da tarde"
    }
  }'

Filtrar Negociações por Canal de Marketing

Buscar todas as negociações de um canal específico:

curl -X GET "https://app.garagem.ai/api/v1/crm/deals?marketingChannelInstanceId=uuid-do-canal&limit=50" \
  -H "Authorization: Bearer sua_api_key"

Atualizar Negociação

Atualizar Etapa e Campos Customizados

curl -X PATCH https://app.garagem.ai/api/v1/crm/deals/{id} \
  -H "Authorization: Bearer sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "uuid-do-deal",
    "data": {
      "stage": "proposta",
      "status": "open",
      "custom": {
        "valor_proposta": 3400,
        "data_proposta": "2024-01-18",
        "observacoes": "Cliente fez proposta abaixo do valor"
      }
    }
  }'

Atualizar Preferências de Busca

curl -X PATCH https://app.garagem.ai/api/v1/crm/deals/{id} \
  -H "Authorization: Bearer sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "uuid-do-deal",
    "data": {
      "custom": {
        "maxPrice": 3800,
        "locations": ["Zona Sul", "Copacabana", "Ipanema", "Leblon"],
        "bedrooms": 3
      }
    }
  }'

Criar Transação de Negociação

Nota: Os endpoints de transação, certidões e contratos podem não estar disponíveis via REST API ainda. Consulte a Referência da API para verificar disponibilidade ou use tRPC diretamente.

Criar uma transação vinculada a uma negociação:

curl -X POST https://app.garagem.ai/api/v1/transaction \
  -H "Authorization: Bearer sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "dealId": "uuid-da-negociacao",
    "listingId": "uuid-do-listing",
    "price": "3500.00",
    "signatureType": "digital",
    "saleType": "cash",
    "usesFgts": false,
    "buyers": [
      {
        "name": "João Silva",
        "email": "[email protected]",
        "phone": "+5511999999999",
        "cpf": "123.456.789-00",
        "documentType": "cpf",
        "role": "buyer"
      }
    ],
    "sellers": [
      {
        "name": "Maria Santos",
        "email": "[email protected]",
        "phone": "+5511888888888",
        "cpf": "987.654.321-00",
        "documentType": "cpf",
        "role": "seller"
      }
    ],
    "commissions": [],
    "specialConditions": []
  }'

Transação de Aluguel com Configurações

curl -X POST https://app.garagem.ai/api/v1/transaction \
  -H "Authorization: Bearer sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "dealId": "uuid-da-negociacao",
    "listingId": "uuid-do-listing",
    "price": "3500.00",
    "signatureType": "digital",
    "saleType": "cash",
    "rentalContractDurationMonths": 12,
    "rentalContractStartDate": "2024-02-01",
    "rentalFirstPaymentAmount": "3500.00",
    "rentalAdjustmentIndex": "ipca",
    "rentalAdjustmentPeriodMonths": 12,
    "rentalGuaranteeConfig": {
      "type": "deposit",
      "depositAmount": "10500.00",
      "depositEndDate": "2025-02-01"
    },
    "buyers": [
      {
        "name": "João Silva",
        "email": "[email protected]",
        "phone": "+5511999999999",
        "cpf": "123.456.789-00",
        "documentType": "cpf",
        "role": "buyer"
      }
    ],
    "sellers": [
      {
        "name": "Maria Santos",
        "email": "[email protected]",
        "phone": "+5511888888888",
        "cpf": "987.654.321-00",
        "documentType": "cpf",
        "role": "seller"
      }
    ]
  }'

---

Criar Certidões (Due Diligence)

Criar uma solicitação de certidões para uma transação:

curl -X POST https://app.garagem.ai/api/v1/transaction/triggerCertificateProcessing \
  -H "Authorization: Bearer sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "dealId": "uuid-da-negociacao",
    "person": {
      "tasks": [
        "cpf",
        "rg",
        "comprovante_residencia"
      ]
    },
    "property": {
      "tasks": [
        "matricula",
        "iptu",
        "certidao_negativa_debitos"
      ]
    }
  }'

Resposta:

{
  "success": true,
  "diligenceId": "uuid-da-diligencia",
  "apiKey": {
    "expiresAt": "2024-01-22T10:30:00Z"
  }
}

Tipos de Certidões Disponíveis

Para Pessoa:

• cpf - CPF
• rg - RG
• comprovante_residencia - Comprovante de Residência
• certidao_nascimento - Certidão de Nascimento
• certidao_casamento - Certidão de Casamento

Para Imóvel:

• matricula - Matrícula do Imóvel
• iptu - IPTU
• certidao_negativa_debitos - Certidão Negativa de Débitos
• certidao_habitese - Certidão de Habite-se
• certidao_vigilancia_sanitaria - Certidão de Vigilância Sanitária

---

Criar Contrato

Criar um contrato para uma transação:

Contrato de Venda

curl -X POST https://app.garagem.ai/api/v1/transaction/contract/createContract \
  -H "Authorization: Bearer sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "uuid-da-transacao",
    "documentType": "sale",
    "signers": [
      {
        "email": "[email protected]",
        "name": "João Silva",
        "role": "buyer",
        "contactId": "uuid-do-contato-comprador"
      },
      {
        "email": "[email protected]",
        "name": "Maria Santos",
        "role": "seller",
        "contactId": "uuid-do-contato-vendedor"
      }
    ]
  }'

Contrato de Locação

curl -X POST https://app.garagem.ai/api/v1/transaction/contract/createContract \
  -H "Authorization: Bearer sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "uuid-da-transacao",
    "documentType": "lease",
    "signers": [
      {
        "email": "[email protected]",
        "name": "João Silva",
        "role": "buyer",
        "contactId": "uuid-do-contato-inquilino"
      },
      {
        "email": "[email protected]",
        "name": "Maria Santos",
        "role": "seller",
        "contactId": "uuid-do-contato-proprietario"
      }
    ]
  }'

Contrato com Conteúdo Personalizado

curl -X POST https://app.garagem.ai/api/v1/transaction/contract/createContract \
  -H "Authorization: Bearer sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "uuid-da-transacao",
    "documentType": "sale",
    "content": "CONTRATO DE COMPRA E VENDA\n\nEntre as partes...",
    "signers": [
      {
        "email": "[email protected]",
        "name": "João Silva",
        "role": "buyer"
      },
      {
        "email": "[email protected]",
        "name": "Maria Santos",
        "role": "seller"
      }
    ]
  }'

Tipos de Contrato Disponíveis

• sale - Contrato de Compra e Venda
• lease - Contrato de Locação
• administration - Contrato de Administração
• possession_term - Termo de Posse
• release_agreement - Termo de Quitação
• termination_contract - Distrato / Rescisão
• contract_amendment - Aditivo Contratual

Papéis de Signatários

• buyer - Comprador/Inquilino
• seller - Vendedor/Proprietário
• witness - Testemunha

Resposta:

{
  "id": "uuid-do-contrato",
  "transactionId": "uuid-da-transacao",
  "documentType": "sale",
  "status": "draft",
  "createdAt": "2024-01-15T10:30:00Z"
}

---

Buscar Imóveis com Typesense

O Garagem usa Typesense para busca avançada de imóveis. Você pode obter a configuração e fazer buscas de forma segura.

Obter Configuração do Typesense

Obter a configuração de busca (inclui chave scoped com permissões limitadas):

curl -X GET "https://app.garagem.ai/api/v1/real-estate/config/getTypesenseSearchConfig" \
  -H "Authorization: Bearer sua_api_key"

Resposta:

{
  "apiKey": "xyz-scoped-search-key-123",
  "nodes": [
    {
      "host": "typesense.example.com",
      "port": 443,
      "protocol": "https"
    }
  ],
  "indexName": "listings_tenant_123",
  "cacheSearchResultsForSeconds": 60,
  "defaultFilters": "visibility:=public && stage:=active",
  "customFacets": ["custom_area_total", "custom_quartos"],
  "customSearchableFields": ["custom_descricao"]
}

Importante: A apiKey retornada é uma chave scoped com permissões limitadas apenas para busca. Não é uma chave administrativa e não permite modificações.

Buscar Imóveis via Proxy (Recomendado)

Para sites públicos, use o endpoint proxy que não expõe chaves:

curl -X POST https://app.garagem.ai/api/sites/{siteId}/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "apartamento zona sul",
    "query_by": "title,description,neighborhood",
    "filter_by": "type:=rental && price:<=4000",
    "facet_by": "neighborhood,bedrooms",
    "per_page": 12,
    "page": 1
  }'

Resposta:

{
  "found": 25,
  "page": 1,
  "search_time_ms": 12,
  "hits": [
    {
      "document": {
        "id": "uuid-do-listing",
        "title": "Apartamento 2 quartos - Copacabana",
        "type": "rental",
        "price": 3500,
        "bedrooms": 2,
        "neighborhood": "Copacabana",
        "city": "Rio de Janeiro"
      },
      "highlights": [
        {
          "field": "title",
          "snippet": "Apartamento 2 quartos - <mark>Copacabana</mark>"
        }
      ]
    }
  ],
  "facet_counts": [
    {
      "field_name": "neighborhood",
      "counts": [
        { "value": "Copacabana", "count": 10 },
        { "value": "Ipanema", "count": 8 }
      ]
    }
  ]
}

Buscar Imóveis Diretamente no Typesense

Se você precisar fazer buscas diretamente no Typesense, use a chave scoped obtida anteriormente:

curl -X POST https://typesense.example.com:443/collections/listings_tenant_123/documents/search \
  -H "X-TYPESENSE-API-KEY: xyz-scoped-search-key-123" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "apartamento",
    "query_by": "title,description,neighborhood,city",
    "filter_by": "type:=rental && price:<=4000 && bedrooms:>=2",
    "facet_by": "neighborhood,bedrooms,property_type",
    "sort_by": "price:asc",
    "per_page": 20,
    "page": 1
  }'

Exemplos de Filtros

Por tipo e preço:

{
  "filter_by": "type:=rental && price:<=4000 && price:>=2000"
}

Por localização:

{
  "filter_by": "neighborhood:[Copacabana,Ipanema,Leblon]"
}

Por características:

{
  "filter_by": "bedrooms:>=2 && bathrooms:>=1 && property_type:=apartment"
}

Por campos customizados:

{
  "filter_by": "custom_area_total:>=60 && custom_area_total:<=100"
}

Busca com Facetas (Filtros)

Use facet_by para obter contagens de valores:

curl -X POST https://app.garagem.ai/api/sites/{siteId}/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "query_by": "title",
    "facet_by": "neighborhood,bedrooms,property_type,price",
    "max_facet_values": 20,
    "per_page": 0
  }'

Isso retorna apenas as facetas sem resultados, útil para construir filtros dinâmicos.

Busca Geográfica

Buscar imóveis próximos a uma localização:

curl -X POST https://app.garagem.ai/api/sites/{siteId}/search \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "query_by": "title",
    "filter_by": "type:=rental",
    "geo_location": {
      "lat": -22.970722,
      "lng": -43.182365,
      "radius": 5000
    },
    "sort_by": "_geo_distance(location):asc"
  }'

Segurança

Importante:

• A chave retornada por getTypesenseSearchConfig é uma chave scoped com permissões limitadas
• Ela permite apenas busca na collection do seu tenant
• Não permite criar, atualizar ou deletar documentos
• Não permite acessar outras collections
• UseNunca exponha chaves administrativas do Typesense

Para sites públicos, sempre use o endpoint proxy (/api/sites/{siteId}/search) que não requer expor chaves no cliente.

📖 Veja Sites API para documentação completa do endpoint de busca.

---

Mais Informações

Para detalhes completos sobre todos os tipos de campos disponíveis, consulte:

• Sites API - Endpoints públicos para WordPress e sites externos
• Campos Customizados - Documentação completa sobre:
  • Marketing Attribution (nível superior)
  • Preferências de Busca (search preferences)
  • Campos Customizados (custom fields)
  • Campos específicos de Listings