Navegar na documentação

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}/owner nã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 com leads:read; sem ela, esses campos vêm vazios, na mesma forma.
    • Escrita com Idempotency-Key que 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_SCHEDULED com a visita que já existe.
    • Chamados: null no 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.
    • O CRM na API (permissões crm:read e crm: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:read e rent: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.
    • Datas com fuso (2026-10-02T09:00:00-03:00, +00:00) são aceitas e convertidas para UTC — no updatedSince, no since e nas datas do corpo. Antes eram recusadas com 400. Sem fuso, valem como UTC.
    • Webhooks: trocar os types de 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-After e 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.
    • 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 o limit e paginam pelo cursor; arquivada que perdeu relevância sai ARCHIVED com lostRelevance: 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); since no futuro é 400. Os SDKs: o "todas as páginas" dos eventos para no hasMore: false. changedFields sai com os nomes do GET.
    • Clientes: o código de um cliente na lixeira responde 409 lead_in_trash — antes, o PUT pelo código criava outro cliente.
    • Imóveis: o desfecho diz o que aconteceu com o anúncio (UPDATED só 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: summary e message só com leads:read. Confirmação em lote: o mesmo imóvel pedido duas vezes sai DUPLICATE, fora do resumo. Webhook: types: null volta 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.
    • 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 oportunidades FAVORITED passam a trazer favorite, com a resposta.
    • Imóvel: condoFee (condomínio por mês) e landArea (área do terreno) na leitura e na escrita — os mesmos valores que o painel mostra e o feed grava.
    • Correção: radar.eligible do cliente passa a ser false com 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/feed mostra 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. 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 type de cada erro.
    • Coleção do Postman, OpenAPI em JSON e YAML e llms.txt para 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.