Visão geral

Para integrações de Inteligência de Mercado de Imóveis, a Órulo disponibiliza os dados em duas etapas complementares:

1. CSV histórico (onboarding) — arquivo enviado pela equipe de integração no início do projeto, contendo o histórico de variação da região metropolitana contratada (ex.: RMSAO, RMPOA).
2. API (manutenção contínua) — espelho do momento atual, utilizada para manter a base de dados atualizada após a carga inicial.

Recomendamos que o cliente mantenha a base de dados em seu próprio ambiente, com autonomia para personalizar e cruzar as informações conforme necessário. Desenvolvemos nossa API com esse formato em mente. A documentação técnica completa dos endpoints está disponível em documento.orulo.com.br/#section/Uso-por-sistemas-externos/Inteligencia-de-Mercado.

Onboarding

1. Recebimento do CSV histórico

No início da integração, a equipe de integração da Órulo envia um arquivo .csv com o histórico de variação da região metropolitana contratada.

O CSV contém séries mensais de variação por tipologia — métricas agregadas como VGV, vendas, distratos, estoque e preços, com datas de referência. Os campos do CSV são derivados dos dados que a API expõe (por exemplo, VGV = número de unidades × preço médio da unidade); não há informação exclusiva no CSV que não possa ser obtida ou calculada a partir da API.

A importação e o cruzamento do CSV com os dados da API ficam sob responsabilidade do cliente.

2. Carga inicial via API

Após receber suas credenciais (Client ID e Client Secret) da nossa equipe de integração, siga estas etapas para construir o espelho do estado atual:

1. Consulte o endpoint /config para verificar se a integração está ativa para esta aplicação.
2. Obtenha o token de oruloClientAuth e armazene-o. Embora tenha validade de 1 ano, desaconselhamos utilizá-lo como parâmetro para validar sua vida útil, pois essa configuração pode ser alterada internamente por questões de segurança. Recomendamos que você faça as requisições normalmente e, se encontrar algum erro, trate-o adequadamente e solicite um novo token.
3. Obtenha uma listagem de todos os empreendimentos da região contratada através do endpoint /buildings. Armazene todos os IDs retornados, juntamente com suas respectivas datas de atualização no campo updated_at. Este campo será importante para a rotina de sincronização.
4. Acesse individualmente cada empreendimento da listagem através do endpoint /buildings/{buildingId} e cadastre-os com suas respectivas tipologias associadas.
5. Acesse individualmente as unidades vinculadas a cada tipologia através do endpoint /buildings/{buildingId}/typologies/{typologyId}/units e cadastre-as vinculadas à sua tipologia 'pai'.

Rotina de sincronização

Com a base de dados no lado do cliente, é necessário mantê-la atualizada e incluir novos empreendimentos. A API funciona como espelho do momento atual — ela não substitui o histórico recebido no CSV, mas permite atualizar o estado corrente a partir dele.

Recomendamos no máximo uma sincronização por dia. Na prática, integrações de Inteligência de Mercado costumam sincronizar em intervalos maiores (15 a 30 dias), conforme a necessidade do cliente.

Para executar a rotina de sincronização, siga os passos abaixo:

1. Consulte o endpoint /config para certificar-se de que a integração está ativa.
2. Acesse o endpoint /buildings e crie uma nova listagem com IDs associados aos campos updated_at, da mesma forma que na carga inicial.
3. Atualização de empreendimentos: compare a nova listagem com a anterior. Se o updated_at do item na listagem antiga for anterior ao da listagem nova, realize uma requisição em /buildings/{buildingId} com o ID correspondente e substitua todas as informações do empreendimento (incluindo tipologias e unidades).
4. Cadastro de novos empreendimentos: compare as duas listagens e identifique a diferença (A – B). Para os IDs resultantes, faça uma requisição em /buildings/{buildingId}, cadastre o empreendimento em sua base e sincronize tipologias e unidades conforme os passos 4 e 5 do onboarding.

Atenção ⚠️ 

Cada elemento associado a um empreendimento (building) possui identificadores únicos (IDs). Esses IDs desempenham um papel crucial no processo de atualização, permitindo distinguir entre elementos novos e aqueles que foram removidos. Os IDs de fotos, plantas e outros elementos são exclusivos e não se repetem. Portanto, é seguro excluir qualquer foto cujo ID não seja mais retornado na listagem.

Considerações finais

O conteúdo deste artigo foi elaborado com base em nossas conversas com os clientes ao longo dos anos em que atuamos neste segmento, em colaboração com nossa equipe de desenvolvimento. No entanto, caso tenha chegado a alguma conclusão diferente, sinta-se à vontade para proceder da maneira que julgar mais adequada.

Ao final do desenvolvimento da integração, conduzimos uma etapa de homologação em que validamos principalmente o volume de acessos à API, verificando se as consultas estão dentro do esperado. A montagem e o cruzamento dos dados históricos (CSV) com o espelho atual (API) ficam sob responsabilidade do cliente.