Guia Rápido

O Garagem oferece três portas de entrada para integrações — escolha de acordo com o caso de uso:

Porta	Quando usar	Auth
REST (/api/v1)	Scripts, parceiros, plugin WordPress, automações server-to-server que leem/escrevem dados	API key
MCP (/api/mcp)	Claude Desktop, ChatGPT, Cursor e outros clientes LLM que agem em seu nome	OAuth 2.1
Webhooks de Canais	Site, landing page ou sistema externo que envia leads para o Garagem	Token por canal

Webhooks de canais também são a porta de saída para eventos do sistema — o Garagem chama sua URL quando algo acontece (lead criado, mensagem recebida, assinatura concluída, etc.). Veja Webhooks e Eventos para o catálogo completo.

Todas as portas respeitam o mesmo modelo de permissões da plataforma.

---

Caminho 1 — REST (/api/v1)

1. 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!)

2. Fazer sua Primeira Requisição

Teste a API criando uma negociação simples:

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 de Teste",
    "dealType": "rental",
    "stage": "lead",
    "status": "open",
    "currency": "BRL",
    "contacts": [
      {
        "name": "João Silva",
        "email": "[email protected]",
        "phone": "+5511999999999",
        "role": "buyer"
      }
    ]
  }'

3. Base URL

Todos os endpoints REST estão disponíveis em:

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

Autenticação

Todas as requisições precisam incluir sua API key:

Opção 1 - Header Authorization:

Authorization: Bearer sua_api_key_aqui

Opção 2 - Header x-api-key:

x-api-key: sua_api_key_aqui

Rate limits

Cada API key tem um teto de 1000 requisições por hora, contado por chave (não por IP nem por conta). Quem compartilha a mesma chave — varredura diária, plugin, MCP, scripts — divide a mesma cota.

A janela reinicia 1 hora após a última requisição aceita. Se o teto estoura em poucos minutos, a chave só volta a responder depois que essa hora passar.

Toda resposta autenticada inclui:

Cabeçalho	Significado
X-RateLimit-Limit	Teto da janela atual
X-RateLimit-Remaining	Quanto ainda resta
X-RateLimit-Reset	Unix timestamp (UTC, segundos) de quando reinicia

Quando o teto é atingido a API devolve HTTP 429 (não 401) com Retry-After em segundos. 401 fica reservado para credencial inválida ou expirada. Pare a sonda ao ver Remaining chegar a 0 — não espere o 429.

---

Caminho 2 — MCP (/api/mcp)

Para conectar Claude Desktop, ChatGPT, Cursor, Claude Code ou qualquer cliente MCP:

1. Criar uma conexão MCP

1. Acesse Configurações → Desenvolvedor → Conexões MCP
2. Clique em Nova conexão
3. Escolha o modo de acesso:
   • Ferramentas padrão (recomendado para a maioria dos casos)
   • Acesso completo ao surface (avançado — para você operando o Garagem via terminal com Claude Code/Cursor)
4. Copie o client ID gerado

2. Conectar o cliente

Em clientes modernos como Claude Desktop, basta apontar o servidor MCP para:

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

O próprio cliente cuida do fluxo OAuth. Autorize no navegador e consinta aos scopes desejados.

3. Descobrir as ferramentas

Dois endpoints públicos permitem inspecionar o servidor antes de conectar:

# Scopes disponíveis
curl https://app.garagem.ai/api/mcp/.well-known/scopes

# Catálogo de ferramentas com JSON Schema
curl https://app.garagem.ai/api/mcp/.well-known/tools

Guia completo

Veja 12 - MCP para detalhes sobre scopes, modos de acesso, conexão com cada cliente e o modo “Acesso completo ao surface”.

---

Caminho 3 — Webhooks de Canais (Inbound Leads)

Para enviar leads de um site, landing page ou sistema externo direto para o Garagem. Não precisa gerenciar API key — cada canal tem seu próprio pathToken que funciona como credencial.

1. Criar um canal de marketing

1. Acesse Configurações → Canais na sua conta Garagem
2. Crie um novo canal (ex: “Site Institucional”, “Landing Page Google Ads”)
3. Copie o pathToken gerado (formato: chnl_2xxxxxxxxxx)

2. Enviar um lead

O endpoint aceita um payload flexível — mande apenas o que você tem:

curl -X POST \
  -H "Content-Type: application/json" \
  "https://app.garagem.ai/api/webhooks/channels/chnl_seu_token_aqui" \
  -d '{
    "contactName": "João Silva",
    "contactEmail": "[email protected]",
    "contactPhone": "+5511999999999",
    "listingId": "uuid-do-anuncio",
    "originLeadId": "meu-sistema-lead-12345",
    "message": "Tenho interesse neste imóvel",
    "utmSource": "google",
    "utmCampaign": "apartamentos-zona-sul"
  }'

Resposta padrão (202):

{
  "ok": true,
  "accepted": true
}

3. Principais recursos

• listingId / listingCode — UUID do anúncio ou código do catálogo. O Garagem resolve o imóvel e preenche tipologia, bairro, valor, fotos. Não precisa traduzir código → UUID.
• originLeadId — idempotência: se você reenviar o mesmo lead, o Garagem retorna a negociação existente sem criar duplicata.
• visitDate + visitTime — cria automaticamente uma tarefa de visita vinculada.
• UTM / Atribuição — utmSource, utmMedium, utmCampaign, gclid, landingPage (URL absoluta ou caminho começando com /), referrer (URL absoluta). Um landingPage ou referrer inválido é ignorado e não impede a criação do lead.
• Captação de imóvel — envie "destination": "listing" (ou leadType: "seller_lead") para que o lead crie um anúncio (proprietário) em vez de uma negociação (comprador/inquilino).

Por padrão a resposta é 202 com { "ok": true, "accepted": true } (processamento assíncrono). Use ?sync=true se precisar do dealId na resposta. ?sync=true espera a criação da negociação, não a atribuição do corretor. Para o assignedToId, use ?sync=assignment.

Guia completo

Veja 08 - Webhooks e Eventos para a lista completa de campos, exemplos por caso de uso e o catálogo de eventos outbound (deal.created, channel.message.received, agent.execution.completed, etc.).

---

Homologação

Não há ambiente sandbox. Lead, corretor, imóvel e webhook criados pela API entram no tenant de produção e nos relatórios. Não há flag de teste que os exclua.

Para exercitar sem publicar:

• Use um canal de marketing só de homologação e o marketingChannelInstanceId dele nos leads de teste.
• Crie o imóvel com visibility private, ou fora da etapa ativa, e sem publicação em portal. A Sites API não o lista.
• Aponte o webhook para uma URL de homologação e assine listing.updated, listing.workflow.transitioned e listing.deleted.
• Apague depois com DELETE /api/v1/crm/deals/{id} e com a exclusão do anúncio no CRM. A exclusão do anúncio emite listing.deleted.

Próximos Passos

• Veja Exemplos Práticos para casos de uso comuns
• Consulte a Referência da API para documentação completa dos endpoints REST
• Consulte 12 - MCP para o fluxo MCP completo
• Consulte 08 - Webhooks e Eventos para inbound de leads e eventos outbound