Este guia é destinado a desenvolvedores de CRMs parceiros ou equipes que mantêm CRMs próprios para imobiliárias e desejam integrar seus sistemas ao serviço de Catálogo da Órulo.

Os empreendimentos e todos os seus elementos associados (fotos, plantas, tipologias, contatos comerciais, etc.) possuem IDs únicos e imutáveis. Eles são essenciais para:

IDs nunca são reutilizados. Se um ID deixar de ser retornado pela API, ele pode ser removido com segurança do sistema local.

Quando a imobiliária configura suas credenciais (Client ID e Secret) no CRM, siga este processo inicial:

Rotas da API de catálogo usam o prefixo /api/v2/. As rotas /oauth/* (OAuth2 / Doorkeeper) não levam esse prefixo.

Na documentação oficial, o identificador do empreendimento pode aparecer como :building_id; neste guia usamos {buildingId} com o mesmo significado.

Obtenha o token de acesso via oruloClientAuth com POST (recomendado pela RFC 6749: evita expor client_secret em query string, logs de proxy e histórico).

Embora o token tenha longa validade, o CRM deve apenas tratar erros de autenticação e solicitar um novo token conforme necessário. Não é necessário verificar ou controlar validade manualmente.

O corpo da resposta (campos como name, callback_url, active, updated_at, etc.) está descrito na documentação oficial da API.

Paginação: a listagem é paginada. Utilize os parâmetros de query page e results_per_page. O número de itens por página não pode ultrapassar 500. A resposta inclui, entre outros campos, building_ids (lista de objetos com id e updated_at), total, page e total_pages. O CRM deve percorrer todas as páginas (por exemplo, incrementando page até alcançar total_pages); caso contrário, verá no máximo 500 empreendimentos e o catálogo ficará incompleto.

Exemplo ilustrativo de estrutura de resposta:

Para cada buildingId listado:

Essa operação deve ser realizada apenas uma vez, na primeira sincronização.

As atualizações de empreendimentos (novos, alterados ou removidos) são notificadas via Webhook.

Os eventos são divididos em dois tipos de payload (com e sem client_id) porque o objeto da notificação muda:

• Sem client_id — atualização de catálogo (active, removed): a mudança refere-se ao empreendimento no catálogo (dados ou situação geral). A ação esperada do CRM é a mesma para quem consome esse catálogo (reprocessar o building_id ou tratar remoção ampla). Não há client_id porque o evento não é específico de uma integração — não é preciso rotear por credencial. Quando várias integrações usam a mesma URL de webhook, a Órulo envia um único POST por URL e por evento nesses casos, reduzindo volume sem perder o significado do evento.
• Com client_id — mudança de distribuição (added_to_distribution, excluded_from_distribution): a mudança é por integração (o empreendimento entra ou sai da distribuição daquela credencial). Várias integrações podem compartilhar a mesma URL sem parametrizá-la; o client_id no corpo identifica qual integração deve incluir ou retirar o empreendimento. Por isso o envio permanece por integração (a mesma URL pode receber mais de um POST, com client_id distinto em cada um). Esses eventos podem refletir ações feitas na área do cliente na plataforma — por exemplo, quando a imobiliária opta por não receber mais aquele empreendimento na distribuição da integração (ou volta a incluí-lo). O webhook comunica o efeito para o CRM alinhar a base local.

Deduplicação temporal: além do envio único por URL nos casos descritos acima, a infraestrutura pode consolidar eventos muito próximos no tempo (da ordem de menos de cinco minutos) para o mesmo empreendimento e integração. Duas alterações em sequência rápida podem resultar em um único webhook. O CRM deve tratar o processamento de forma idempotente e pode complementar com a reconciliação periódica da seção 3.4.

A configuração é realizada pelo time de integrações da Órulo. Para isso, o CRM deve fornecer uma URL pública que aceite requisições POST.

O endpoint do CRM deve responder HTTP 200 a cada evento, para confirmar o recebimento. O processamento (consultar a API, inserir, atualizar ou remover) pode continuar depois, inclusive de forma assíncrona. Respostas diferentes de 200 (timeout, 4xx ou 5xx) são tratadas como falha de recebimento.

A notificação é enviada em POST para a URL configurada, com Content-Type: application/json.

Atualização de empreendimento (status active ou removed): o payload não inclui client_id, pois o evento não discrimina integração.

Mudança de distribuição (status added_to_distribution ou excluded_from_distribution): o payload inclui client_id (identificador da integração, por exemplo o UID da aplicação OAuth).

Exemplo com added_to_distribution:

Preparação futura: se em algum cenário eventos com status *_from_distribution for enviado sem client_id, o CRM deve estar preparado para interpretar como remoção/adição do empreendimento em todas as integrações (otimização administrativa possível no futuro). Trate essa regra de forma defensiva na implementação.

Quando o CRM receber o webhook:

Significa que o empreendimento foi criado ou atualizado. O CRM deve reprocessar esse buildingId realizando a seguinte requisição:

No JSON de resposta, as imagens e as plantas vêm nos arrays images e floor_plans, cada item com um campo id (string). O CRM deve guardar localmente a lista de images[].id e floor_plans[].id da última sincronização. Ao receber o webhook e obter a resposta atual do GET /api/v2/buildings/{buildingId}, compare essas listas: se houver IDs novos ou IDs que deixaram de existir na resposta, chame os endpoints dedicados (que retornam URLs em múltiplas dimensões):

• GET /api/v2/buildings/{buildingId}/images
• GET /api/v2/buildings/{buildingId}/floor_plans

Exemplo: na última sync, images tinham os IDs "456" e "789". Após o webhook, o GET retorna images com "456" e "999". O ID "789" sumiu (remova localmente o que dependia dele) e "999" é novo — nesse caso, chame GET /api/v2/buildings/{buildingId}/images para obter as URLs do novo item.

Somente quando houver alteração nesses conjuntos de IDs é obrigatório refazer o download completo por esses endpoints; caso contrário, basta atualizar os demais campos do empreendimento a partir do GET do building.

Depois disso:

• Se o empreendimento não existir no CRM → inserir.
• Se já existir → sobrescrever todos os dados atualizados.
• Remover somente elementos cujo ID não existe mais.

Indica que o empreendimento entrou na distribuição da integração identificada por client_id. O fluxo de sincronização é o mesmo do active (consultar GET /api/v2/buildings/{buildingId} e, se necessário, imagens e plantas). Integrações que não precisam distinguir entrada na distribuição de uma atualização comum podem tratar added_to_distribution como equivalente a active.

O empreendimento não deve mais ser considerado ativo. O CRM deve realizar um soft delete, ou seja:

O empreendimento deve ser totalmente removido da base daquela integração (use client_id para rotear quando várias integrações compartilham a mesma URL). Em geral, trata-se de hard delete no escopo dessa integração:

Além dos webhooks, recomenda-se que o CRM execute periodicamente uma rotina de reconciliação combinando dois passos:

1. Empreendimentos ativos: repetir o fluxo da seção 2.3 (todas as páginas de GET /api/v2/buildings/ids/active) e, para cada building_id, reprocessar o empreendimento como na primeira sincronização ou ao receber active (detalhes em 3.3).
2. Empreendimentos removidos: na mesma execução da rotina, chamar GET /api/v2/buildings/ids/removed com updated_after (por exemplo, data/hora da última reconciliação concluída com sucesso) e tratar cada building_id retornado como no webhook com status removed (soft delete; ver 3.3). Restrição: o intervalo entre updated_after e o momento atual não pode exceder 90 dias; se a última execução foi há mais tempo, use uma data mais recente ou faça consultas em etapas. Parâmetros, paginação (se houver) e formato da resposta: documentação oficial da API.

Isso cobre casos em que um evento de atualização ou de remoção não foi processado (falha temporária no endpoint do CRM, indisponibilidade, fila interna, deduplicação temporal de webhooks, etc.).

Orientação operacional para o integrador: executar essa rotina completa (ativos e removidos) no máximo uma vez por dia e no mínimo uma vez por semana, ajustando conforme volume e criticidade, respeitando o teto diário para não sobrecarregar a API nem o próprio sistema. O webhook continua sendo o canal principal; esta rotina é reconciliação de segurança, não substituto do fluxo em tempo real.

O endpoint de links de publicação tem como finalidade que o CRM informe à Órulo os links dos empreendimentos publicados no site da imobiliária. Essa é uma exigência das anunciantes e o não atendimento deste requisito pode causar restrições no acesso à API e na geração dos eventos de notificação. Sempre que um imóvel é publicado ou despublicado, esses links precisam ser atualizados.

O endpoint recebe um array de links. Sempre substitui os links anteriores existentes para aquele buildingId. Exemplo:

Isso ocorre quando o CRM gera páginas por tipologia. Exemplo:

• Empreendimento ID 123
• Tipologias: Studio, 1 Dorm, 2 Dorms

O CRM pode enviar:

Todos esses links são válidos e devem ser processados como páginas vinculadas ao mesmo empreendimento.

O oruloEndUserAuth utiliza o OAuth2 e é destinado a acessar dados comerciais em tempo real, sem armazenamento em banco. Esses dados incluem:

• Contatos comerciais: nome, telefones, e-mails, WhatsApp e página de contato
• Percentual de comissão
• Website do empreendimento
• Arquivos de apoio à venda: tabelas de preços, memorial descritivo, etc.
• Detalhes de oportunidades: textos, valores, datas, promoções e premiações

Configuração obrigatória: informar ao time de integrações da Órulo a URL de callback (redirectURI) que será utilizada pelo corretor para autorizar a aplicação.

Requisitos da redirectURI: em produção, a URI de callback deve usar HTTPS (configuração do servidor OAuth). Em desenvolvimento ou ambientes não produtivos, HTTP em localhost costuma ser aceito para testes. Confirme sempre na documentação oficial e com o time de integrações se houver dúvida.

5.1 Processo de autorização

1. Gerar link de autorização para o corretor:

https://www.orulo.com.br/oauth/authorize?client_id={clientId}&redirect_uri={redirectURI}&response_type=code

2. Após a autorização, trocar o código recebido (code) por um access token com POST e corpo application/x-www-form-urlencoded (evita expor client_secret na query):

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

client_id={clientId}&client_secret={clientSecret}&code={code}&redirect_uri={redirectURI}&grant_type=authorization_code

3. Usar o token retornado (END_USER_TOKEN) para consultar os endpoints em tempo real:

GET /api/v2/buildings/1234
Authorization: Bearer END_USER_TOKEN

Observação

Como os dados obtidos via oruloEndUserAuth requerem rastreabilidade, eles devem ser consumidos em tempo real e não armazenados no banco de dados. A implementação do oruloEndUserAuth é opcional; caso não seja adotada, é suficiente utilizar o link da página do empreendimento na Órulo, contido no campo orulo_url.

Referência enxuta para implementação defensiva (detalhes por endpoint na documentação oficial da API):

O conteúdo deste artigo foi elaborado com base em conversas com clientes ao longo dos anos em que a Órulo atua neste segmento, em colaboração com a equipe de desenvolvimento. Esta abordagem é a mais recomendada para a construção da integração. No entanto, caso tenha chegado a alguma conclusão diferente, sinta-se à vontade para proceder da maneira que julgar mais adequada. É importante ressaltar que, ao final do desenvolvimento da integração pelo cliente, conduz-se uma etapa de homologação para validar os pontos mencionados neste documento.