Documentação da API Garagem

Bem-vindo à documentação da API do Garagem, uma plataforma completa de CRM para profissionais do mercado imobiliário.

📖 Novo aqui? Comece pelo Guia Rápido para fazer sua primeira requisição em minutos.

---

🚪 Escolhendo a porta de entrada

O Garagem oferece cinco portas de integração — todas respeitam o mesmo modelo de permissões (RBAC) que a interface web:

	/api/v1 (REST)	Sites SDK (@garagem-ai/site-sdk)	/api/mcp (MCP)	Webhooks de Canais (Inbound)	Listings por Canal (Outbound)
Quando usar	Scripts, parceiros, plugin WordPress, automação server-to-server	Sites custom em Next.js, React, apps headless de imóveis	Claude Desktop, ChatGPT, Cursor, Claude Code, agentes MCP customizados	Site, landing page ou sistema externo enviando leads para o Garagem	Parceiro/landing consumindo imóveis filtrados do Garagem
Autenticação	API key (Bearer ou x-api-key)	Nenhuma (endpoints públicos por site)	OAuth 2.1 + Dynamic Client Registration	Token por canal (pathToken)	Bearer token por canal
Shape	REST + OpenAPI	TypeScript SDK (fetchers tipados + blocos shadcn)	Model Context Protocol (tool calling)	POST JSON com payload flexível	GET/POST JSON (Typesense-compat)
Documentação	Seções 02-07 e 10-11	sdk.garagem.site/docs	12 - MCP	08 - Webhooks e Eventos	13 - Listings por Canal

Além disso, eventos outbound (o Garagem chamando a sua URL quando algo acontece) também são webhooks — veja 08 - Webhooks e Eventos.

Um corretor faz as mesmas coisas em qualquer porta; um administrador tem acesso ampliado em qualquer porta.

---

🚀 Começando com REST (/api/v1)

Obter sua API Key

1. Acesse Configurações → Desenvolvedor na sua conta Garagem
2. Clique em Criar API Key
3. Dê um nome descritivo (ex: “Integração Site”, “Automação Leads”)
4. Copie a chave gerada (ela só será exibida uma vez!)

Autenticação

Authorization: Bearer sua_api_key_aqui

Base URL

https://app.garagem.ai/api/v1

🚀 Começando com MCP (/api/mcp)

1. Acesse Configurações → Desenvolvedor → Conexões MCP
2. Clique em Nova conexão e escolha o modo de acesso (Padrão, Específicas, Acesso completo ou Vincular a um agente)
3. Aponte seu cliente MCP (Claude Desktop, Cursor, ChatGPT) para:

   https://app.garagem.ai/api/mcp

4. O cliente cuida do fluxo OAuth; autorize no navegador e consinta aos scopes desejados

Veja o guia completo em 12 - MCP.

---

📚 Índice da Documentação

Guias

Documento	Descrição
01 - Guia Rápido	Primeiros passos e primeira requisição
09 - Exemplos Práticos	Casos de uso completos com código

CRM

Documento	Descrição
02 - Negociações (Deals)	CRUD de negociações, funil de vendas, contatos
03 - Tarefas (Tasks)	CRUD de tarefas, agendamentos, follow-ups

Imóveis

Documento	Descrição
04 - Imóveis (Properties)	CRUD de imóveis, características, localização
05 - Anúncios (Listings)	CRUD de anúncios, visibilidade, preços

Integrações

Documento	Descrição
06 - Campos Customizados	Marketing attribution, preferências de busca
07 - Compartilhamento	Links públicos, visibilidade de campos, domínios
08 - Webhooks e Eventos	Notificações em tempo real
10 - Sites API	API pública para WordPress e sites externos
11 - Plugin WordPress	Instalação e uso do plugin Garagem (WordPress.org + CRM)
12 - MCP	Conectar Claude, ChatGPT, Cursor e outros clientes LLM
13 - Listings por Canal	Feed JSON de imóveis por canal (Bearer, critérios + slots)
14 - Condomínios por Canal	Importação em lote de condomínios/edifícios por canal + feed de leitura
15 - Conversas e Canais	Inventário + reply portátil via API key (webhook → REST)

Sites SDK (Next.js / React)

Recurso	Descrição
@garagem-ai/site-sdk	Pacote npm — SDK tipado para buscar imóveis, sites e dados de CMS
Docs	Quickstart, referência de API, receitas
Blocos	Componentes React compatíveis com shadcn — instale com npx shadcn add
Registry	Catálogo JSON de blocos (consumido pelo shadcn CLI e v0.dev)

---

📊 Resumo de Endpoints

CRM

GET    /api/v1/crm/deals           # Listar negociações
GET    /api/v1/crm/deals/{id}      # Buscar negociação
POST   /api/v1/crm/deals           # Criar negociação
PATCH  /api/v1/crm/deals/{id}      # Atualizar negociação
DELETE /api/v1/crm/deals/{id}      # Deletar negociação

GET    /api/v1/crm/tasks           # Listar tarefas
GET    /api/v1/crm/tasks/{id}      # Buscar tarefa
POST   /api/v1/crm/tasks           # Criar tarefa
PATCH  /api/v1/crm/tasks/{id}      # Atualizar tarefa
DELETE /api/v1/crm/tasks/{id}      # Deletar tarefa

Imóveis

GET    /api/v1/real-estate/properties/{id}   # Buscar imóvel
POST   /api/v1/real-estate/properties        # Criar imóvel + anúncios
PATCH  /api/v1/real-estate/properties/{id}   # Atualizar imóvel

GET    /api/v1/real-estate/listings          # Listar anúncios (Postgres, shape completo)
GET    /api/v1/real-estate/listings/search   # Buscar anúncios (Typesense, filtros ricos)
GET    /api/v1/real-estate/listings/{id}     # Buscar anúncio
DELETE /api/v1/real-estate/listings/{id}     # Deletar anúncio

Messaging (inventário + reply portátil)

GET    /api/v1/messaging/conversations          # Listar conversas (RBAC + privacy)
GET    /api/v1/messaging/conversations/detail   # Detalhe + histórico
GET    /api/v1/messaging/channels               # Inventário de canais
POST   /api/v1/messaging/reply                  # Responder (texto ou listing cards)
POST   /api/v1/messaging/send                   # Enviar texto ou template HSM

Veja 15 - Conversas e Canais para o padrão webhook (metadados) → fetch REST (detalhe) → reply/send.

Sites (Público - Sem Autenticação)

GET    /api/sites/resolve             # Resolver site por domínio ou ID
GET    /api/sites/{siteId}/public-config  # Configuração pública do site
POST   /api/sites/{siteId}/search     # Buscar imóveis (Typesense)
GET    /api/sites/{siteId}/property/{id}  # Detalhes do imóvel
GET    /api/sites/{siteId}/locations  # Localizações disponíveis
GET    /api/sites/share/{token}       # Resolver link de compartilhamento
POST   /api/sites/share/{token}       # Resolver link com senha

MCP (Model Context Protocol)

POST   /api/mcp                       # Endpoint principal (OAuth 2.1)
GET    /api/mcp/.well-known/scopes    # Catálogo público de scopes
GET    /api/mcp/.well-known/tools     # Catálogo público de ferramentas

Veja 12 - MCP para o fluxo completo de conexão.

Listings por Canal (Feed JSON)

GET    /api/webhooks/channels/{pathToken}/listings         # Listar imóveis (Bearer)
POST   /api/webhooks/channels/{pathToken}/listings         # Listar imóveis (body JSON)
GET    /api/webhooks/channels/{pathToken}/listings/slots   # Discovery dos slots do canal

Veja 13 - Listings por Canal para critérios, slots/destaque e exemplos.

Condomínios por Canal (Importação em lote + Feed)

POST   /api/webhooks/channels/{pathToken}/buildings/import   # Importar condomínios em lote (push)
GET    /api/webhooks/channels/{pathToken}/buildings/import   # Importar de um feed externo (pull, ?feedUrl=)
GET    /api/webhooks/channels/{pathToken}/buildings          # Listar condomínios (Bearer)
POST   /api/webhooks/channels/{pathToken}/buildings          # Listar condomínios (body JSON)

Veja 14 - Condomínios por Canal para o formato do payload, deduplicação e sincronização em rede.

---

🔑 Conceitos Principais

Negociação (Deal)

Representa uma oportunidade de negócio com contatos, etapas do funil e histórico.

{
  "title": "Lead do Site",
  "dealType": "rental",
  "stage": "lead",
  "contacts": [{ "name": "João", "email": "[email protected]", "role": "buyer" }]
}

Imóvel (Property) vs Anúncio (Listing)

• Property = imóvel físico (quartos, área, localização)
• Listing = oferta comercial (preço, visibilidade, tipo de transação)

{
  "property": { "type": "apartment", "bedrooms": 2 },
  "listings": [
    { "type": "rental", "price": "3500", "visibility": "public" },
    { "type": "sale", "price": "450000", "visibility": "private" }
  ]
}

Visibilidade

Campo	Valores	Descrição
visibility	public, private	Controla se o anúncio aparece em buscas públicas
priceVisibility	public, private	Controla se o preço é exibido

📖 Veja 05 - Anúncios para detalhes.

---

📖 Referência OpenAPI

Especificação completa disponível em:

https://app.garagem.ai/api/docs