Documentação da API

FOURCS Real Estate API

Conecte seus sistemas à plataforma: crie leads, leia o catálogo de imóveis, receba eventos por webhook e assine a agenda. REST, JSON e autenticação por chave — os dados de cada cliente ficam isolados.

REST + JSONChave por clienteRate limit 120/minWebhooks assinados

Comece aqui

A base da API é o domínio do seu site, no caminho /api/v1/ext. Toda requisição precisa de uma chave de API enviada no cabeçalho.

Base URL
https://SEU-DOMINIO.com.br/api/v1/ext

Autenticação (use um dos dois cabeçalhos)
Authorization: Bearer SUA_CHAVE
X-API-Key: SUA_CHAVE
🔑 Onde pegar a chave: no painel administrativo, em Configurações → Integrações → Chaves de API → Nova chave. A chave é exibida uma única vez — guarde com segurança. Cada chave é isolada por cliente (tenant).

Leads

POST/api/v1/ext/leads

Cria um lead no funil a partir de um sistema externo (site próprio, hotsite, chatbot). Anti-duplicidade: se já existir um lead com o mesmo telefone/e-mail, ele é reaproveitado e a mensagem é anexada. Limite de 120 requisições por minuto.

curl -X POST https://SEU-DOMINIO.com.br/api/v1/ext/leads \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Souza",
    "phone": "11999998888",
    "email": "maria@email.com",
    "message": "Tenho interesse no apartamento do Itaim",
    "source": "SITE",
    "propertyId": 42
  }'

# Resposta
{ "success": true, "data": { "id": 1875, "deduped": false } }

Campos: name (obrigatório), phone, email, message, source, propertyId (opcionais). O lead entra na etapa inicial do funil e dispara as automações configuradas.

GET/api/v1/ext/leads/:id

Lê os dados de um lead do cliente.

curl https://SEU-DOMINIO.com.br/api/v1/ext/leads/1875 \
  -H "Authorization: Bearer SUA_CHAVE"

Imóveis

GET/api/v1/ext/properties

Lista os imóveis ativos do cliente (projeção pública). Parâmetros: limit (1–100, padrão 50) e type (APARTMENT, HOUSE, LAND, COMMERCIAL, LAUNCH…).

curl "https://SEU-DOMINIO.com.br/api/v1/ext/properties?limit=20&type=APARTMENT" \
  -H "X-API-Key: SUA_CHAVE"

# Resposta (resumo dos campos)
{ "success": true, "data": [
  { "id": 42, "type": "APARTMENT", "name": "Edifício Aurora",
    "slug": "edificio-aurora", "price": 850000, "areaMin": 78,
    "bedrooms": 3, "suites": 1, "parkingSpots": 2,
    "city": "São Paulo", "neighborhood": "Itaim",
    "highlightPhoto": "https://.../foto.webp", "status": "AVAILABLE" }
]}

Webhooks de saída

Receba eventos em tempo real no seu endpoint. Configure a URL e o segredo em Configurações → Integrações → Webhooks. Cada envio é assinado (HMAC) com o seu segredo para você validar a autenticidade.

lead.createdNovo lead criado no funil
lead.stage_changedLead mudou de etapa no Kanban
appointment.bookedVisita agendada
lead.deletedLead removido
POST no seu endpoint
Headers: X-FOURCS-Signature: sha256=<hmac do corpo com seu segredo>
Body: { "event": "lead.created", "data": { ...dados do lead... } }

Feed de agenda (iCal)

Assine a agenda de visitas em qualquer calendário (Google, Apple, Outlook) por uma URL .ics assinável, gerada no painel em Agenda.

GET https://SEU-DOMINIO.com.br/api/v1/agenda/feed/SEU_TOKEN.ics

Erros & limites

Todas as respostas seguem o mesmo formato. Erros trazem success:false, uma mensagem e um code para tratar no seu lado.

{ "success": false, "error": "Informe a API key (Authorization: Bearer ...)", "code": "NO_API_KEY" }

Códigos comuns
401 NO_API_KEY / INVALID_API_KEY   chave ausente ou inválida
400 VALIDATION_ERROR                corpo inválido (veja "details")
404 NOT_FOUND                       recurso não encontrado
429 (rate limit)                    acima de 120 req/min em /leads

Precisa de um endpoint que não está aqui? Fale com a equipe FOURCS — a API cresce conforme os módulos. Novos recursos (imóveis via API, propostas, comissões) entram no mesmo padrão de chave e resposta.