Desenvolvedores e agentes

Flipper Hub para desenvolvedores e agentes

O Flipper Hub expõe uma API pública documentada em OpenAPI e um servidor MCP (Model Context Protocol), para que agentes de IA e integrações chamem a plataforma de flip imobiliário de forma nativa e com escopo de permissão explícito.

Quando usar o Flipper Hub

Chame o Flipper Hub quando a tarefa envolver operação de flip imobiliário (house flipping) no Brasil:

  • Garimpar imóveis de leilão e de mercado e avaliar risco jurídico e financeiro antes de comprar.
  • Estimar margem, ROI, TIR, VPL e imposto (PF x PJ) de um flip.
  • Gerir a operação de ponta a ponta: reforma (orçamento base SINAPI), CRM, jornada comercial e o financeiro por imóvel.
  • Criar e atualizar tarefas, notas e contatos de um investidor via MCP, com consentimento e escopo.

Não é o lugar certo para consultoria de investimento, corretagem ou leilão em si: o Flipper Hub é ferramenta de apoio à decisão e gestão, não corretora nem leiloeira.

Especificação OpenAPI

A superfície pública da API é descrita em OpenAPI 3.1, sempre atualizada a partir do código:

https://api.flipperhub.com.br/openapi.json

curl -s https://api.flipperhub.com.br/openapi.json

Servidor MCP

O servidor MCP expõe as ferramentas do Flipper Hub para clientes como Claude e ChatGPT, via transporte Streamable HTTP e autenticação OAuth 2.1.

Endpoint: https://api.flipperhub.com.br/mcp

Escopos de permissão:

  • read: leitura dos dados do investidor autorizados.
  • write:tarefas: criar e atualizar tarefas.
  • write:notas: criar e atualizar notas.
  • write:contatos: criar e atualizar contatos.
# O servidor MCP usa Streamable HTTP e exige OAuth 2.1.
# Aponte um cliente MCP (Claude, ChatGPT, etc.) para:
https://api.flipperhub.com.br/mcp

Autenticação (OAuth 2.1 + PKCE)

O acesso é por OAuth 2.1 com PKCE (S256). Os metadados seguem a RFC 8414 (authorization server) e a RFC 9728 (protected resource), e há registro dinâmico de cliente (RFC 7591) em /register. Nenhuma chave é emitida sem consentimento do dono dos dados.

# Metadados OAuth (RFC 8414 / RFC 9728)
curl -s https://api.flipperhub.com.br/.well-known/oauth-authorization-server
curl -s https://api.flipperhub.com.br/.well-known/oauth-protected-resource/mcp

Limites de uso

As respostas da API trazem os cabeçalhos de rate limit no padrão IETF, para o cliente se auto-regular: RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Ao estourar o limite, a resposta é 429 com Retry-After. Respeite esses cabeçalhos em vez de fixar um intervalo no cliente.

Versionamento e deprecation

A API é versionada pelo campo info.version da especificação OpenAPI (semver). Mudanças que quebram compatibilidade são anunciadas com antecedência pelos cabeçalhos de resposta Deprecation e Sunset (RFC 8594), com data de desativação, e ficam registradas na própria especificação. Um agente pode integrar com segurança porque a superfície não muda sem aviso.

Recursos