Mudanças e versões
A versão atual é v1 (contrato 1.0.0). O que muda é anunciado aqui antes de valer.
Política de versões
- Acrescentar não quebra: campos, eventos, rotas e valores novos podem chegar a qualquer momento. O seu sistema deve tolerar campo que ele não conhece.
- O que quebra uma integração existente sai numa versão nova (
/v2). A versão anterior continua funcionando por pelo menos 12 meses depois do aviso, publicado aqui e mandado por e-mail ao dono da conta. - Os valores de código (
VENDA,ACTIVE, os subtipos) são os mesmos da plataforma, sem tradução no meio.
O que mudou
- Correção:
PUT /v1/properties/{propertyId}/ownernão apaga mais a chave PIX, a conta bancária e os dados pessoais quando o proprietário ganha ou perde o CPF entre duas gravações. Homônimos sem documento não herdam os dados um do outro. - As rotas de atendimento (
/contacts,/next-step,/temperature,/lost) respondem com o nome, os telefones, o e-mail e as anotações do cliente só para a chave comleads:read; sem ela, esses campos vêm vazios, na mesma forma. - Escrita com
Idempotency-Keyque termina em 504: a mesma chave devolve o mesmo 504 em vez de gravar de novo. Confira pela leitura antes de repetir com outra chave. - Agendar a MESMA visita de novo (cliente, imóvel, dia e hora) responde
ALREADY_SCHEDULEDcom a visita que já existe. - Chamados:
nullno PATCH limpa a descrição, o orçamento e o prestador; o ensaio recusa o contrato desfeito e mostra a aprovação pendente do proprietário, como a gravação. NaN,Infinity, lista ou objeto num campo de valor fechado e JSON aninhado demais respondem 400 — antes, 500.GET /v1/rent/contracts/{contractId}não cria mais o link do inquilino.
- Correção:
- O CRM na API (permissões
crm:readecrm:write): as visitas, as propostas e as vendas de cada cliente e de cada imóvel; o proprietário do imóvel; e, para registrar, o contato com a resposta, o próximo passo, a temperatura, a perda com o motivo, agendar, remarcar, cancelar e registrar a visita, a proposta com as rodadas e o desfecho. Toda escrita tem ensaio. - A Locação na API (permissões
rent:readerent:write): os contratos, os meses com a situação da cobrança, os repasses a fazer e os chamados — abrir, corrigir, mover e cancelar. Nada que mova dinheiro: a baixa, o repasse e o acerto seguem na tela. - O cliente ganha
crm: a temperatura, o próximo passo, a resposta do último contato e o motivo da perda. - Novo erro
module_required(403): a escrita do CRM ou da Locação numa conta sem o módulo ligado. - As permissões novas não entram sozinhas nas chaves que já existem: crie uma chave com elas, no painel.
- O CRM na API (permissões
- Datas com fuso (
2026-10-02T09:00:00-03:00,+00:00) são aceitas e convertidas para UTC — noupdatedSince, nosincee nas datas do corpo. Antes eram recusadas com 400. Sem fuso, valem como UTC. - Webhooks: trocar os
typesde um endereço vale para a entrega seguinte — antes, por até 1 minuto, os avisos saíam pelo filtro antigo. O reenvio manual de uma entrega passa mesmo fora do filtro. - O limite por segundo é aproximado: estourá-lo deixa recusas (429) por alguns minutos, mesmo em ritmo baixo. Os SDKs esperam o
Retry-Aftere tentam até 5 vezes no 429, numa cota separada das falhas (maxRateLimitRetries); o servidor MCP tenta uma vez antes de devolver o 429 ao agente. - Imóveis: com o sync automático do feed desligado, o imóvel gravado pela API não sai do ar por estar fora do feed — antes, uma sincronização manual o arquivava 36 h depois. Com o sync ligado, o feed é a origem e o que não estiver no XML sai, como antes.
- Datas com fuso (
- Os códigos de erro são todos em minúsculas: os de liberação de acesso, que vinham em MAIÚSCULAS, passam a
ip_not_allowed,suspended,plan_not_eligible… (a página de cada um não mudou de endereço). - Parâmetro de consulta que a rota não aceita é 400
unknown_param, com a lista dos aceitos — antes era ignorado em silêncio. GET /v1/matches: as novas respeitam olimite paginam pelo cursor; arquivada que perdeu relevância saiARCHIVEDcomlostRelevance: true; o imóvel de parceiro sai sem o site e sem a comissão.GET /v1/events: pedir de novo logo depois do fim devolve a lista vazia e o mesmo cursor (antes, 500);sinceno futuro é 400. Os SDKs: o "todas as páginas" dos eventos para nohasMore: false.changedFieldssai com os nomes do GET.- Clientes: o código de um cliente na lixeira responde 409
lead_in_trash— antes, oPUTpelo código criava outro cliente. - Imóveis: o desfecho diz o que aconteceu com o anúncio (
UPDATEDsó quando ele muda; só conflito,CONFIRMED), e todo ensaio passa pelas mesmas recusas da gravação. - Cidades e bairros: o cursor só vale na rota e na conta de origem; cidade sem lista de bairros responde 200 com
hasCatalog: false; estado que não existe é 400. - Parcerias:
summaryemessagesó comleads:read. Confirmação em lote: o mesmo imóvel pedido duas vezes saiDUPLICATE, fora do resumo. Webhook:types: nullvolta a todos os avisos. - O 405 traz
Allow; o bloqueio por IP diz o IP que chegou e a chamada barrada não conta na cota; as permissões saem em inglês;launches:write, que não tinha rota, saiu do catálogo.
- Os códigos de erro são todos em minúsculas: os de liberação de acesso, que vinham em MAIÚSCULAS, passam a
GET /v1/leads/{leadId}/radar: por que o cliente não recebe recomendações — o que falta no cadastro e o que falta no mercado, com o que fazer.GET /v1/leads/{leadId}/favorites: os favoritos do cliente e o que ele respondeu pelo link (❤️, ❌ e a observação). As oportunidadesFAVORITEDpassam a trazerfavorite, com a resposta.- Imóvel:
condoFee(condomínio por mês) elandArea(área do terreno) na leitura e na escrita — os mesmos valores que o painel mostra e o feed grava. - Correção:
radar.eligibledo cliente passa a serfalsecom o atendimento Fechado ou Perdido — esse cliente não recebe recomendações, mesmo com o perfil completo.
- SDKs oficiais em TypeScript, Python e PHP, gerados deste contrato: um método por rota, as páginas percorridas sozinhas, nova tentativa que nunca duplica uma escrita e a conferência da assinatura do webhook.
- Exemplos de resposta (sucesso e erros) na coleção do Postman e no OpenAPI. A coleção pública do Postman acompanha cada versão.
POST /v1/feed/sync: o seu sistema avisa que a carteira mudou e a ImobyFlow busca o link do feed na hora, sem esperar as 6 horas;GET /v1/feedmostra o resultado.- Servidor MCP em
https://api.imobyflow.com.br/mcp: agentes de IA leem e atualizam a conta com a mesma chave. Toda escrita roda em ensaio e só grava com confirmação. - Nova página "Integrar o seu CRM": o feed dos portais sem programar, o mapa de cada campo do VRSync para a API e uma ficha por CRM (Kenlo, Vista, Jetimob, Imobzi, Superlógica e CV CRM).
1.0.0
- Portal do desenvolvedor em português e inglês, gerado do contrato OpenAPI 3.1.
- Uma página por código de erro — o endereço que vem no
typede cada erro. - Coleção do Postman, OpenAPI em JSON e YAML e
llms.txtpara assistentes de IA. - Botão "Experimente" em cada rota: chama a API do navegador com a sua chave (leitura de verdade, escrita sempre em modo ensaio) e explica cada campo da resposta — o JSON anotado.
- Webhooks assinados (Standard Webhooks), com nova tentativa por cerca de 21 horas, desligamento automático, reenvio e evento de teste.
- Eventos (
GET /v1/events): o que mudou na conta, em ordem, com 30 dias de memória. - Avisos por e-mail: chave vencendo, cota do mês em 80% e 100%, endereço de webhook desligado.
- Lotes de até 500 imóveis ou clientes.
- Captação: a mesa, os aceitos e o aceite, com permissão e termo próprios.
- Ações: descartar e restaurar oportunidade, mover parceria e a lixeira com a trava de encolhimento.
- Escrita de clientes (código do seu sistema, vínculo pelo contato, consentimento) e de imóveis (fotos por endereço, modo ensaio,
Idempotency-Key). - Leitura: imóveis, clientes, oportunidades, parcerias, equipe e lançamentos.
- A fundação: chaves por conta, liberação conta a conta,
GET /v1/me, listas de valores e o catálogo de cidades e bairros.
- A fundação: chaves por conta, liberação conta a conta,