Oportunidades (Radar)
As oportunidades que o Radar encontra entre imóveis e clientes — da própria carteira e de parceiros —, com a mesma regra de exibição do painel.
- GET/v1/properties/{propertyId}/matches— Oportunidades de um imóvel
- GET/v1/leads/{leadId}/matches— Oportunidades de um cliente
- GET/v1/leads/{leadId}/radar— Por que o cliente não recebe recomendações
- GET/v1/matches— Oportunidades da conta
- POST/v1/matches/{matchId}/dismiss— Descartar oportunidade
- POST/v1/matches/{matchId}/restore— Restaurar oportunidade
As rotas
/v1/properties/{propertyId}/matchesOportunidades de um imóvel
Os clientes que combinam com o imóvel. Só clientes da própria carteira — cliente de parceiro nunca aparece no seu imóvel.
radar:readParâmetros no caminho
propertyIdstringobrigatório- Id do imóvel (
prop-…).
Resposta200OK
datalista de Matchobrigatório- As oportunidades.
nextCursorstringobrigatóriopode vir nulo- Cursor da próxima página (nulo = acabou).
Exemplo
curl -X GET 'https://api.imobyflow.com.br/v1/properties/prop-3f9a1c2b7d4e/matches' \
-H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
-H 'Accept-Language: pt-BR'Erros desta rota
/v1/leads/{leadId}/matchesOportunidades de um cliente
Os imóveis que servem ao cliente — da carteira e de parceiros.
radar:readParâmetros no caminho
leadIdstringobrigatório- Id do cliente (
lead-…).
Resposta200OK
datalista de Matchobrigatório- As oportunidades.
nextCursorstringobrigatóriopode vir nulo- Cursor da próxima página (nulo = acabou).
Exemplo
curl -X GET 'https://api.imobyflow.com.br/v1/leads/lead-7c2e9a1b3d5f/matches' \
-H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
-H 'Accept-Language: pt-BR'Erros desta rota
/v1/leads/{leadId}/radarPor que o cliente não recebe recomendações
O diagnóstico que o painel mostra no cliente: o que falta no cadastro (pending) e o que falta no mercado (misses — quantos imóveis o Radar avaliou e deixou de fora, por quê e o que fazer). Os motivos são recontados a cada alteração no cliente; um imóvel compatível que entra depois vira recomendação na hora, sem esperar por isso.
radar:readParâmetros no caminho
leadIdstringobrigatório- Id do cliente (
lead-…).
Resposta200OK
dataLeadRadarDiagnosisobrigatório- O diagnóstico.
Exemplo
curl -X GET 'https://api.imobyflow.com.br/v1/leads/lead-7c2e9a1b3d5f/radar' \
-H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
-H 'Accept-Language: pt-BR'Erros desta rota
/v1/matchesOportunidades da conta
As oportunidades. As NOVAS (o padrão) são a caixa do painel: por prioridade, até o limite de oportunidades abertas do corretor — as demais entram à medida que a caixa esvazia; pagine pelo cursor. As outras situações vêm da mais mexida para a menos, e as arquivadas incluem as que perderam relevância (lostRelevance: true). As de parceiros seguem a regra de exibição do painel: sem assinatura ativa, o parceiro fica escondido (locked); o site e a comissão do imóvel do parceiro ficam só na tela. O nome do cliente só sai com leads:read na chave.
radar:readFiltros e paginação
limitinteger- Itens por página: de 1 a 100 (padrão 50).
cursorstring- O
nextCursorda página anterior. A lista acabou quando ele vem nulo. Ele vale só para esta rota e esta conta. statusstring- Situação.um de
NEWFAVORITEDARCHIVEDREQUESTED scopestring- Origem.um de
INTERNALNETWORKLAUNCH ownerAccountIdstring- Só os de um corretor.
Resposta200OK
datalista de Matchobrigatório- As oportunidades.
nextCursorstringobrigatóriopode vir nulo- Cursor da próxima página (nulo = acabou).
Exemplo
curl -X GET 'https://api.imobyflow.com.br/v1/matches' \
-H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
-H 'Accept-Language: pt-BR'Erros desta rota
/v1/matches/{matchId}/dismissDescartar oportunidade
A decisão do corretor, tomada no seu sistema. Oportunidade favoritada não se descarta.
radar:writeAceita modo ensaioAceita Idempotency-KeyParâmetros no caminho
matchIdstringobrigatório- Id da oportunidade. Tem
#: mande codificado (%23).
Filtros e paginação
dryRunbooleantrue= modo ensaio: valida e diz o que aconteceria, sem gravar nada.
Resposta200OK
dataMatchobrigatório- O objeto como ficou.
resultMatchWriteResultobrigatório- O desfecho.
Exemplo
# Modo ensaio: nada é gravado. Tire o ?dryRun=true para gravar de verdade.
curl -X POST 'https://api.imobyflow.com.br/v1/matches/m%23prop-3f9a1c2b7d4e%23lead-7c2e9a1b3d5f%23L/dismiss?dryRun=true' \
-H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
-H 'Accept-Language: pt-BR' \
-H "Idempotency-Key: $(uuidgen)"Erros desta rota
/v1/matches/{matchId}/restoreRestaurar oportunidade
Volta a oportunidade descartada para as novas.
radar:writeAceita modo ensaioAceita Idempotency-KeyParâmetros no caminho
matchIdstringobrigatório- Id da oportunidade. Tem
#: mande codificado (%23).
Filtros e paginação
dryRunbooleantrue= modo ensaio: valida e diz o que aconteceria, sem gravar nada.
Resposta200OK
dataMatchobrigatório- O objeto como ficou.
resultMatchWriteResultobrigatório- O desfecho.
Exemplo
# Modo ensaio: nada é gravado. Tire o ?dryRun=true para gravar de verdade.
curl -X POST 'https://api.imobyflow.com.br/v1/matches/m%23prop-3f9a1c2b7d4e%23lead-7c2e9a1b3d5f%23L/restore?dryRun=true' \
-H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
-H 'Accept-Language: pt-BR' \
-H "Idempotency-Key: $(uuidgen)"Erros desta rota
Os objetos
RadarMiss
Um motivo pelo qual imóveis avaliados não viraram recomendação.
codestringobrigatório- O motivo, em código estável. Motivo novo sem código sai
OTHER, com a contagem.um deOUT_OF_BUDGETOTHER_NEIGHBORHOODOTHER_CITYOTHER_TYPEOTHER_PURPOSELOW_SCOREAWAITING_REVIEWNOT_SHAREDDEVELOPER_INACTIVEDEVELOPMENT_OFF_MARKETPROPERTY_INCOMPLETELEAD_INCOMPLETEOTHER countintegerobrigatório- Quantos imóveis pararam neste motivo.
labelstringobrigatório- O motivo, por extenso.
actionstringobrigatóriopode vir nulo- O que fazer a respeito (nulo em
OTHER).
LeadRadarDiagnosis
Por que o cliente recebe, ou não, recomendações.
leadIdstringobrigatório- Id do cliente.
statestringobrigatórioACTIVE,ARCHIVEDouDELETED.um deACTIVEARCHIVEDDELETEDblockedBystringobrigatóriopode vir nulo- Por que o cliente está fora do Radar antes de qualquer pendência: arquivado, na lixeira, ou com o atendimento encerrado (Fechado ou Perdido). Nulo: nada o impede. Fora do Radar, o diagnóstico de mercado não sai.um de
ARCHIVEDDELETEDFUNNEL_CLOSED blockedLabelstringobrigatóriopode vir nulo- O motivo, por extenso.
eligiblebooleanobrigatório- Recebe recomendações: nada o impede (
blockedBynulo) e não há pendência no cadastro. pendinglista de stringobrigatório- O que falta no CADASTRO — os mesmos códigos do
radardo cliente.um dePURPOSE_MISSINGPROPERTY_TYPES_MISSINGCITY_MISSINGCITY_NOT_IN_CATALOGBUDGET_MISSINGSALE_BUDGET_MISSINGRENT_BUDGET_MISSINGOTHER labelslista de stringobrigatório- As mesmas pendências, por extenso.
tierstringobrigatóriopode vir nulo- O degrau do perfil de busca: quanto mais específico, mais recomendações o Radar guarda para o cliente. Nulo: o Radar ainda não avaliou o cliente, ou ele está fora do Radar (
blockedBy).um dePRECISEGOODBROADINCOMPLETE tierLabelstringobrigatóriopode vir nulo- O degrau, por extenso.
reachintegerobrigatóriopode vir nulo- Quantas recomendações novas o Radar guarda para este cliente.
opportunitiesintegerobrigatóriopode vir nulo- Quantas recomendações novas ele tem agora.
misseslista de RadarMissobrigatório- O que falta no MERCADO: por que os imóveis avaliados ficaram de fora, do motivo mais frequente ao menos (até 5). Vazio quando nada ficou de fora, quando o cadastro está incompleto (veja
pending) ou quando o cliente está fora do Radar (blockedBy).
PropertySnapshot
O retrato do imóvel no par — o mesmo do card. Campos que a tela esconde saem nulos.
titlestringobrigatóriopode vir nulo- Título.
typestringobrigatóriopode vir nulo- Subtipo.
purposestringobrigatóriopode vir nulo- Finalidade do par.
purposeslista de stringobrigatório- Finalidades do imóvel.
pricenumberobrigatóriopode vir nulo- Preço (venda, ou aluguel quando o par é de locação).
priceFrombooleanobrigatório- O preço é "a partir de" (lançamento).
rentPricenumberobrigatóriopode vir nulo- Aluguel.
citystringobrigatóriopode vir nulo- Cidade.
neighborhoodstringobrigatóriopode vir nulo- Bairro.
bedroomsintegerobrigatóriopode vir nulo- Quartos.
bathroomsintegerobrigatóriopode vir nulo- Banheiros.
parkingSpotsintegerobrigatóriopode vir nulo- Vagas.
areanumberobrigatóriopode vir nulo- Área, em m².
coverPhotostringobrigatóriopode vir nulo- Capa.
listingUrlstringobrigatóriopode vir nulo- Anúncio (nulo quando a tela também esconde, e sempre nulo no imóvel de parceiro,
NETWORK). commissionPercentnumberobrigatóriopode vir nulo- Comissão de venda, em % (nula no imóvel de parceiro — fica na tela).
rentCommissionMonthsnumberobrigatóriopode vir nulo- Comissão de locação, em aluguéis (nula no imóvel de parceiro).
splitListingPercentnumberobrigatóriopode vir nulo- Parte de quem captou, em % (nula no imóvel de parceiro).
lastConfirmedAtstringobrigatóriopode vir nulo- Última confirmação de disponibilidade.
deliveryDatestringobrigatóriopode vir nulo- Entrega (lançamento).
developmentIdstringobrigatóriopode vir nulo- Empreendimento.
developmentNamestringobrigatóriopode vir nulo- Nome do empreendimento.
ClientSnapshot
O retrato do cliente no par.
maskedbooleanobrigatório- O cliente é de parceiro e está mascarado.
statusstringobrigatóriopode vir nulo- Etapa do atendimento.
preApprovedbooleanobrigatório- Crédito pré-aprovado.
purposeslista de stringobrigatório- Finalidades procuradas.
propertyTypeslista de stringobrigatório- Tipos procurados.
regionslista de stringobrigatório- Regiões, por extenso.
priceMinnumberobrigatóriopode vir nulo- Piso.
priceMaxnumberobrigatóriopode vir nulo- Teto.
bedroomsintegerobrigatóriopode vir nulo- Quartos.
parkingSpotsintegerobrigatóriopode vir nulo- Vagas.
areaMinnumberobrigatóriopode vir nulo- Área mínima.
namestringobrigatóriopode vir nulo- Nome — só com a permissão
leads:readna chave e só quando a tela também mostra. Telefone, nunca.
Counterpart
O parceiro do outro lado.
accountIdstringobrigatório- Id da conta do parceiro.
namestringobrigatóriopode vir nulo- Nome.
typestringobrigatóriopode vir nulo- Tipo de conta.
organizationstringobrigatóriopode vir nulo- Imobiliária do parceiro.
crecistringobrigatóriopode vir nulo- CRECI.
creciVerifiedbooleanobrigatório- CRECI conferido.
phonestringobrigatóriopode vir nulo- Telefone.
Match
Uma oportunidade: um imóvel que serve a um cliente.
idstringobrigatório- Id da oportunidade (
m#{imóvel}#{cliente}#{lado}). Tem#: mande codificado (%23) no caminho. scopestringobrigatórioINTERNAL(da própria carteira),NETWORK(com parceiros) ouLAUNCH(lançamento).um deINTERNALNETWORKLAUNCHstatusstringobrigatórioNEW,FAVORITED,ARCHIVEDouREQUESTED(virou pedido de parceria).scoreintegerobrigatório- Nota de 0 a 100.
reasonslista de stringobrigatório- Por que combina.
gapslista de stringobrigatório- O que não combina.
propertyIdstringobrigatóriopode vir nulo- Imóvel.
leadIdstringobrigatóriopode vir nulo- Cliente.
ownerAccountIdstringobrigatóriopode vir nulo- O corretor da casa que recebe a oportunidade.
ownerNamestringobrigatóriopode vir nulo- Nome dele.
lockedbooleanobrigatório- Oportunidade de parceiro sem assinatura ativa — o parceiro fica escondido, como na tela.
lostRelevancebooleanobrigatório- Deixou de combinar depois de uma mudança.
propertyPropertySnapshotobrigatóriopode vir nulo- O imóvel.
clientClientSnapshotobrigatóriopode vir nulo- O cliente.
counterpartCounterpartobrigatóriopode vir nulo- O parceiro (nulo quando é da casa ou está escondido).
favoriteMatchFavoriteobrigatóriopode vir nulo- A resposta do cliente ao favorito — só em
FAVORITEDe comleads:readna chave. createdAtstringobrigatório- Quando foi criado (UTC).
updatedAtstringobrigatório- Última alteração (UTC).
MatchFavorite
O que o cliente respondeu sobre este imóvel, pelo link dos favoritos.
addedAtstringobrigatório- Quando entrou nos favoritos do cliente (UTC).
reactionstringobrigatóriopode vir nuloLIKE(gostou) ouDISLIKE(não gostou). Nulo: ainda não respondeu.um deLIKEDISLIKEreactionAtstringobrigatóriopode vir nulo- Quando respondeu (UTC).
commentstringobrigatóriopode vir nulo- A observação que o cliente escreveu.
commentAtstringobrigatóriopode vir nulo- Quando escreveu (UTC).
MatchWriteResult
O desfecho.
outcomestringobrigatórioAPPLIED; em ensaio,WOULD_APPLY.dryRunbooleanobrigatório- Foi um ensaio.