8. Integração ReadOnly API

En esta página

Neste guia, tentaremos mostrar de forma simples a maneira de associar anúncios a uma determinada integração de ReadOnly (somente leitura). Além disso, explicaremos como configurar corretamente os callbacks para receber notificações sobre as distintas ações que podem ser realizadas com os anúncios no portal.

Para o guia, utilizaremos duas interfaces pertencentes a um integrador: uma de leitura (LEC) e outra de leitura e escrita (LES). A de leitura e escrita já possui anúncios criados e associados para algumas de suas empresas associadas.

Ao consultar as imobiliárias com a interface de LEC obtém-se:

{
“number”: 0,
“size”: 4,
“total”: 4,
“content”: [
{
“codigoInmobiliaria”: “Prueba_guia_2_e1”,
“idNavplat”: 30345987,
“nombre”: “Inmobiliaria de Prueba Prueba_guia_2_e1”,
“habilitadoDesde”: 1575547036000
},
{
“codigoInmobiliaria”: “Prueba_guia_2_e2”,
“idNavplat”: 30345989,
“nombre”: “Inmobiliaria de Prueba Prueba_guia_2_e2”,
“habilitadoDesde”: 1575547037000
},
{
“codigoInmobiliaria”: “Prueba_guia_2_e3”,
“idNavplat”: 30345991,
“nombre”: “Inmobiliaria de Prueba Prueba_guia_2_e3”,
“habilitadoDesde”: 1575547039000
},
{
“codigoInmobiliaria”: “Prueba_guia_2_e4”,
“idNavplat”: 30345993,
“nombre”: “Inmobiliaria de Prueba Prueba_guia_2_e4”,
“habilitadoDesde”: 1575547040000
}
]
}

Ao realizar a mesma ação com a interface de LES, obtém-se o mesmo resultado.

A seguir, buscaremos o resumo dos anúncios de uma imobiliária específica. Como exemplo, utilizaremos a empresa “Prueba_guia_2_e2”, que tem dois anúncios.

Ao consultar pelo resumo dos anúncios da imobiliária com a interface de LES obtém-se:

{
“number”: 0,
“size”: 2,
“total”: 2,
“content”: [
{
“idAvisoNavplat”: 45491025,
“codigoAviso”: “15A2D2C2C069BFB3A318FB841FD8FC25_e2_a1”,
“idDesarrolloNavplat”: null,
“codigoDesarrollo”: null,
“tipoDeAviso”: “AVISO_CLASIFICADO”,
“titulo”: “Prueba_guia_2 – Casa En Venta”,
“fechaModificado”: “2019-12-05 06:57:18.0”,
“fechaModificacion”: 1575547038000,
“publicacion”: “SIMPLE”,
“claveInterna”: null,
“dataModificacao”: 1575547038000,
“publicação”: “SIMPLE”
},
{
“idAvisoNavplat”: 45491027,
“codigoAviso”: “15A2D2C2C069BFB3A318FB841FD8FC25_e2_a3”,
“idDesarrolloNavplat”: null,
“codigoDesarrollo”: null,
“tipoDeAviso”: “AVISO_CLASIFICADO”,
“titulo”: “Prueba_guia_2 – Edificio En Venta”,
“fechaModificado”: “2019-12-05 06:57:18.0”,
“fechaModificacion”: 1575547038000,
“publicacion”: “SIMPLE”,
“claveInterna”: null,
“dataModificacao”: 1575547038000,
“publicação”: “SIMPLE”
}
]
}

Ao realizar a mesma consulta com a interface de LEC, obtém-se o mesmo resultado, mas com os códigos de anúncios distintos:

{
“number”: 0,
“size”: 2,
“total”: 2,
“content”: [
{
“idAvisoNavplat”: 45491025,
“codigoAviso”: null,
“idDesarrolloNavplat”: null,
“codigoDesarrollo”: null,
“tipoDeAviso”: “AVISO_CLASIFICADO”,
“titulo”: “Prueba_guia_2 – Casa En Venta”,
“fechaModificado”: “2019-12-05 06:57:18.0”,
“fechaModificacion”: 1575547038000,
“publicacion”: “SIMPLE”,
“claveInterna”: null,
“dataModificacao”: 1575547038000,
“publicação”: “SIMPLE”
},
{
“idAvisoNavplat”: 45491027,
“codigoAviso”: null,
“idDesarrolloNavplat”: null,
“codigoDesarrollo”: null,
“tipoDeAviso”: “AVISO_CLASIFICADO”,
“titulo”: “Prueba_guia_2 – Edificio En Venta”,
“fechaModificado”: “2019-12-05 06:57:18.0”,
“fechaModificacion”: 1575547038000,
“publicacion”: “SIMPLE”,
“claveInterna”: null,
“dataModificacao”: 1575547038000,
“publicação”: “SIMPLE”
}
]
}

<aside> ⚠️

Importante: aqui começam as diferenças entre as interfaces. Embora ambas tenham as mesmas empresas associadas, a interface de LEC não tem seus próprios anúncios associados. Isso significa que ela não receberá notificações sobre ações realizadas nos anúncios ou consultas sobre eles no portal. Para solucionar isso e associar o anúncio à interface, devemos utilizar o endpoint:

PUT /v1/inmobiliarias/{codigoInmobiliaria}/avisos/{codigoAviso}/asociar/{idAviso}

</aside>

Ao realizar esta ação, também deixamos o anúncio associado à interface de LEC.

Como exemplo, utilizaremos a imobiliária “Prueba_Guia_2_e2” e associaremos o anúncio com idAviso = 45491025 com o código “CodigoPersonalizadoGuia”.

A URL solicitada é: http://api-zp.sandbox.open.navent.com/v1/inmobiliarias/Prueba_guia_2_e2/avisos/CodigoPersonalizadoGuia/asociar/45491025?access_token=*******

E a resposta:

{
“code”: “ok”,
“respuesta”: “El aviso con id 45491025 de la inmobiliaria Prueba_guia_2_e2 se asocio al codigoAviso CodigoPersonalizadoGuia.”,
“resposta”: “El aviso con id 45491025 de la inmobiliaria Prueba_guia_2_e2 se asocio al codigoAviso CodigoPersonalizadoGuia.”
}

O anúncio já ficou associado e com o código personalizado pelo integrador. Ao consultar novamente o resumo de anúncios, agora obtemos a seguinte resposta

{
“number”: 0,
“size”: 2,
“total”: 2,
“content”: [
{
“idAvisoNavplat”: 45491025,
“codigoAviso”: “CodigoPersonalizadoGuia”,
“idDesarrolloNavplat”: null,
“codigoDesarrollo”: null,
“tipoDeAviso”: “AVISO_CLASIFICADO”,
“titulo”: “Prueba_guia_2 – Casa En Venta”,
“fechaModificado”: “2019-12-05 06:57:18.0”,
“fechaModificacion”: 1575547038000,
“publicacion”: “SIMPLE”,
“claveInterna”: null,
“dataModificacao”: 1575547038000,
“publicação”: “SIMPLE”
},
{
“idAvisoNavplat”: 45491027,
“codigoAviso”: null,
“idDesarrolloNavplat”: null,
“codigoDesarrollo”: null,
“tipoDeAviso”: “AVISO_CLASIFICADO”,
“titulo”: “Prueba_guia_2 – Edificio En Venta”,
“fechaModificado”: “2019-12-05 06:57:18.0”,
“fechaModificacion”: 1575547038000,
“publicacion”: “SIMPLE”,
“claveInterna”: null,
“dataModificacao”: 1575547038000,
“publicação”: “SIMPLE”
}
]
}

A interface de LEC difere da de LES em que não permite realizar ações que modifiquem ou mudem o estado dos anúncios. Pelo contrário, a interface de LES possui essa capacidade, e qualquer mudança realizada através dela será refletida na interface de LEC. Se for tentada uma ação indevida com a interface de LEC, será gerado um erro com a mensagem correspondente:

{
“code”: “error_inesperado”,
“message”: “Access is denied”
}

É importante ter em conta o endpoint "Resumo de Desarrollos", que proporciona informação sobre todos os desenvolvimentos imobiliários online e suas unidades:

GET /v1/inmobiliarias/{codigoInmobiliaria}/desarrollos/online/resumen

Configuração dos callbacks

Uma vez associado o anúncio, podemos proceder à configuração dos callbacks. Esta funcionalidade permite receber notificações sobre distintas ações que são realizadas sobre os anúncios. Por exemplo, uma consulta pelo telefone no portal.

Para configurá-lo, deve-se utilizar o endpoint:

PUT /v1/configuracion/callbacks

Este endpoint recebe um objeto com a seguinte informação:

URL: url onde o callback será realizado. É obrigatório enviar a url e deve começar com http:// ou https://.
authorizationHeaderKey: key para adicionar ao header como autorização. É opcional e por default é Authorization.
authorizationHeaderValue: valor com token ou cadeia encriptada para a autorização do callback. Se este valor estiver atribuído e authorizationHeaderKey não tiver valor, então a key no header será Authorization.
lenguajeCallbackBody: é opcional, EN para inglês, ES para espanhol, PT para português.

Para configurar callbacks para a interface de LEC utiliza-se a seguinte informação:

{
“url”: “<https://prueba.open.navent.com/callbacks”>,
“authorizationHeaderKey”: “token”,
“authorizationHeaderValue”: “Password”,
“lenguajeCallbackBody”: “ES”
}

Como segunda ação, simulamos uma mensagem de um possível cliente no portal. O integrador é notificado do evento e nos envia a solicitação com a seguinte mensagem: