Documentação e API do Imóveis na Bio

Quando usar o Imóveis na Bio

Use para entender a plataforma de página de imóveis e CRM para corretores, consultar uma página publicada ou registrar o interesse que um visitante pediu para compartilhar com um corretor. Para ações privadas, opere somente em nome de um usuário que autorizou esse acesso.

Não use como portal de busca de todos os imóveis do mercado, serviço de validação de anúncios, integração de mensagens do WhatsApp ou fonte de contatos para disparos. O WhatsApp é um canal externo. Não existe GraphQL nem servidor MCP público. Conteúdo de imóveis é fornecido pelos corretores e pode conter dados desatualizados.

Contrato, versão e URLs

A API responde em https://api.imoveisna.bio. O contrato estável atual usa o prefixo /api/v1. O OpenAPI 3.1.1 cobre consulta de páginas publicadas, envio autorizado de interesse e contexto da própria conta. Endpoints internos do painel, cobrança, administração e workers não são um catálogo de integração pública.

Mudanças compatíveis podem ser adicionadas à v1. Mudanças incompatíveis exigem uma nova versão principal. Rotas sem versão permanecem somente para compatibilidade do aplicativo atual e não devem ser usadas por novas integrações. Consulte a política pública de ciclo de vida para conhecer os sinais e prazos de descontinuação.

Não acrescente barra final ou query parameters às operações documentadas. Use Accept: application/json na API. Respostas de erro possuem error.code, error.message, error.fields e error.request_id. Um recurso inexistente retorna 404; não tente inferir sua existência pelo carregamento do aplicativo.

• OpenAPI JSON
• Política de ciclo de vida
• Instruções para agentes
• Índice para agentes

Verificar acesso e limites sem autenticação

GET /api/v1/status é um teste de conectividade sem login, API key ou mutação de dados. A resposta identifica a versão estável e aponta para esta documentação e para o OpenAPI.

A operação também retorna RateLimit-Policy e RateLimit. Use-a para validar o cliente e a leitura dos headers antes de acessar uma página real.

curl -i -H 'Accept: application/json' https://api.imoveisna.bio/api/v1/status

Consultar uma página publicada

GET /api/v1/public/pages/{slug} não exige login. Substitua {slug} pelo endereço de uma página real publicada pelo corretor. O JSON contém page, blocks, properties, form, fields, form_gate, settings, design e tracking. Páginas privadas, despublicadas ou de contas indisponíveis não são expostas.

Use fields[].key, required, type e options para conhecer os campos ativos do formulário. Você pode reutilizar o ETag em If-None-Match; uma resposta 304 não contém corpo. O exemplo abaixo usa um endereço ilustrativo e pode retornar 404.

curl -i -H 'Accept: application/json' https://api.imoveisna.bio/api/v1/public/pages/corretor-exemplo

Autenticação e dados privados

GET /api/v1/auth/context exige uma sessão existente. No navegador, o login emite cookies HttpOnly e Secure. Clientes autorizados podem usar Authorization: Bearer com um access token Supabase já emitido para o próprio usuário. Não há emissão de API keys pessoais ou OAuth para aplicativos terceiros documentada neste catálogo.

Nunca peça senhas pelo chat, copie cookies para páginas públicas ou use service_role e chaves administrativas. O token não remove as verificações de associação, conta ativa e autorização. Rotas de mutação preservam as validações de origem e CSRF aplicáveis. Não crie contas ou assinaturas automaticamente para obter acesso.

O comando abaixo pressupõe um access token já fornecido ao ambiente por um fluxo seguro. Não registre o valor do token. Sem credencial válida, espere 401 ou 403 e solicite que o usuário entre pelo site.

curl -i -H "Authorization: Bearer $IMOVEIS_ACCESS_TOKEN" -H "Accept: application/json" https://api.imoveisna.bio/api/v1/auth/context

Registrar um interesse com autorização

POST /api/v1/public/pages/{slug}/leads registra um contato real no CRM. Antes de enviar, mostre ao visitante os dados que serão compartilhados e obtenha sua autorização. Não execute requisições de teste contra produção. Use o formulário publicado, não invente campos obrigatórios e não contorne as proteções anti-spam.

Envie Content-Type: application/json e um objeto fields com as chaves do formulário. É necessário nome, email ou telefone, além dos campos obrigatórios configurados pelo corretor. Para um imóvel específico, envie selected_property_id obtido da mesma página. Envie idempotency_key no corpo e reutilize a mesma chave e o mesmo conteúdo se repetir a mesma intenção após uma falha de rede.

A resposta 201 contém ok, lead_id e message; deduplicated pode indicar repetição idempotente. 409 pode indicar uma chave reutilizada com outro conteúdo; 422 indica dados inválidos. O objeto abaixo é ilustrativo, não um comando para enviar. Troque os campos conforme o contrato público e a autorização da pessoa.

Rastreio não é obrigatório para criar um lead. Sem consentimento de cookies, omita tracking_token, session_id, visitor_id e atribuição de analytics. Quando habilitado e autorizado, o rastreio exige os identificadores e o token retornado pela página juntos. Não reutilize nem fabrique tokens.

{
  "fields": {"nome": "Nome autorizado", "email": "[email protected]"},
  "idempotency_key": "interesse-autorizado-001"
}

Limites, respostas 429 e repetição segura

Operações limitadas anunciam RateLimit-Policy e RateLimit conforme draft-ietf-httpapi-ratelimit-headers-11, um rascunho IETF, ainda não uma RFC final. q é a quota, w a janela em segundos, r o saldo e t os segundos restantes. As janelas atuais são fixas de 60 segundos, por método, rota ou grupo de rotas e identidade/IP. Mais de uma proteção pode ser aplicada à mesma operação.

RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset permanecem para compatibilidade. Reset representa segundos, não uma data Unix. Em 429, aguarde Retry-After e reduza a frequência; esse header tem prioridade. Os limites são sinais operacionais, não garantia de capacidade. Proteções de borda ou de um provedor também podem rejeitar solicitações.

Os headers são expostos por CORS para as origens já autorizadas. Não abrimos novas origens nem removemos autenticação. Respostas com quota por cliente não devem ser compartilhadas por caches. Não faça retries automáticos de pagamentos, criação de conta ou outras ações com efeitos colaterais.

RateLimit-Policy: "default";q=120;w=60
RateLimit: "default";r=119;t=42

HTTP/1.1 429 Too Many Requests
Retry-After: 42
RateLimit: "default";r=0;t=42

HTML, Markdown e descoberta

A página inicial, demonstração e páginas institucionais negociam HTML ou Markdown pelo header Accept. A negociação respeita pesos q, exclusões q=0 e retorna 406 quando nenhum formato disponível é aceito. As duas variantes informam Vary: Accept, Accept-Encoding; a variação Origin é preservada.

Prefira os arquivos .md para leitura direta. /llms.txt oferece orientação e links, /sitemap.xml lista URLs públicas indexáveis e /openapi.json descreve as operações. Login, cadastro, checkout e painel não são documentação pública e mantêm seu funcionamento normal.

• Versão Markdown deste guia
• Sobre o produto
• Contato
• Privacidade