Callbacks

A funcionalidade de callbacks permite que os integradores recebam notificações de eventos vinculados a ações realizadas em anúncios e leads (contatos) já integrados ao Navent Real Estate por meio do Open Navent.

Configuração

Os callbacks podem ser configurados de duas maneiras, uma através do suporte e a outra de forma autônoma com o endpoint PUT /v1/configuracion/callbacks.

Para ambas as configurações se deve fornecer as mesmas informações:

  • url: URL POST onde se realizará o callback. É obrigatório enviar a url e deve começar com http:// o https://
  • authorizationHeaderKey: Key para adicionar ao header como autorização. É opcional e por Authorization padrão.
  • authorizationHeaderValue: Valor com token ou sequência criptografada para autorização do callback. Se esse valor for atribuído, mas a authorizationHeaderKey não tiver valor, então a key no header será Authorization.
  • lenguajeCallbackBody: EN para inglês, ES para espanhol, PT para português. Opcional.

Se optar em configurar através do suporte, deve-se enviar um e-mail para [email protected] ou [email protected] com as informações mencionada acima.

Se optar em configurar através do endpoint, o mesmo recebe um objeto com os campos mencionados. Cabe destacar que a URL é Obrigatória e deve começar com http:// o https://A chave de autorização é enviada no cabeçalho da requisição POST no callback. Por exemplo, para aplicar Basic Authorization de HTTP. Se for Basic Authorization, deverá enviar o token completo, ou seja, com a palavra Basic incluída.

Exemplo:
Basic b3BlbjpjYWxsYmFja3M=

Para verificar se a configuração foi feita corretamente, em ambos os casos, você pode usar o endpoint GET /v1/configuracion/callbacks, que retorna o mesmo objeto que foi enviado no PUT, com as informações configuradas.

Inscrição para eventos de Callback

Uma vez que o serviço de callback tenha sido configurado, ele deve se inscrever em todos os eventos dos quais você deseja obter notificações, para isso você deve usar o seguinte endpoint:

PUT /v1/configuracion/callbacks/{evento}

Os eventos disponíveis são os seguintes:
  • CONTACTO
  • CONTACTO_MENSAJE
  • AVISO_CALIDAD
  • AVISO_ACTIVIDAD
  • AVISO_ESTADO_PUBLICACION
  • CREDITO

 

Também estará à sua disposição um endpoint que lhes permitirá cancelar a inscrição de todos os eventos dos quais não desejam receber notificações:

DELETE /v1/configuracion/callbacks/{evento}

Se você não se inscrever em nenhum evento do Callback, por padrão, você não receberá notificações sobre imóveis.

Diferenças nas respostas de status

Todo callback terá sucesso enquanto NÃO receba como resposta um código 4xx o 5xx (pode ser qualquer um dos status 400 possíveis ou qualquer um dos 500 possíveis), ou seja, todos os 2xx ou 3xx (novamente eles podem ser qualquer um dos status 200 possíveis ou qualquer um dos 300 possíveis) são aceitos. Enquanto o sistema de callbacks puder alcançar o endpoint, a resposta será bem-sucedida. Lembre-se de que as respostas de status são as mesmas quando nos referimos a anúncios de imóveis e empreendimentos

Espera-se uma resposta máxima de 1,5 segundos. Se nenhuma resposta for recebida dentro desse tempo, nosso sistema interpreta que houve um tempo limite e, portanto, um erro. Neste caso, o Callback será repetido como qualquer processo de erro, até que o Callback chegue ao seu destino ou 72 horas se passaram desde a criação do Callback. Após 72 horas, o status de retorno de chamada muda para VENCIDO.

 

DICA: é uma boa prática validar se um retorno de Callback não foi entregue ao cliente verificando o ID do evento.
Eventos

Os eventos que são notificados pelo callback são:

  • Mudança de status em um anúncio
  • Adicionar/Remover um anúncio
  • Se um cliente logado no portal clicar em "Ver Telefone" da imobiliária na publicação
  • Mensagem de um possível cliente através do portal
  • Diferentemente da API pública, os leads de usuários anônimos são notificados. Por exemplo, quando o usuário clica em "Ver Telefone" sem estar conectado ao portal.
  • Mudança de qualidade de um anúncio
  • Ativação, cancelamento ou modificação dos planos de publicação de uma imobiliária

Dependendo do tipo de integração, os eventos são notificados pelo callback ou não. As integrações de Leitura e escritura, recebem notificação de todos os eventos. Em vez disso, as de Somente leitura só recebem notificações de leads, quer dizer, a consulta de telefones e a de mensagens através do portal.

Diferenças a considerar

Quando se consultam leads: AVISO_ESTADO_PUBLICACION notificará o usuário se um anúncio alterar o status de sua publicação, ou seja, quando o mesmo mudar de online para offline ou vice-versa. Em vez disso, AVISO_ACTIVIDAD, além de cumprir a funcionalidade anterior, informará o usuário se o anúncio consultado foi modificado.

Eventos por tipo de evento

Anteriormente, era mostrada a lista de eventos que correspondia a imóveis e empreendimentos, mas, neste momento, tentaremos fornecer uma explicação um pouco mais simples, referindo-se aos tipos de eventos que cada evento dispara.

  • Qualquer modificação no corpo de um anúncio (será notificado em AVISO_ACTIVIDAD).
  • Adicionar/Remover um anúncio (será notificado em AVISO_ACTIVIDAD e AVISO_ESTADO_PUBLICACION).
  • Se um cliente logado no portal clicar em "Ver Telefone" da imobiliária na publicação (será notificado em CONTACTO).
  • Mensagem de um possível cliente através do portal (será notificado em CONTACTO_MENSAJE).
  • Leads de usuários anônimos (A API Pública não os mostra). Por exemplo, quando o usuário clica em "Ver Telefone" sem estar logado no portal (será notificado em CONTACTO).
  • Modificação de qualidade de um anúncio (será notificado em AVISO_CALIDAD)..
  • Ativação, cancelamento ou modificação dos planos de publicação de uma imobiliária (será notificado em CREDITO).
Body Callbacks

O envio de informações do sistema de callback é por região/idioma. Na requisição ao callback configurado, essas informações serão enviadas pelo body. O body depende dos eventos e da região em que o integrador ou o idioma configurado está localizado.

Na sessão de body callbacks, podemos observar o body das possíveis respostas.

Como realizar os testes?
  • Para poder realizar testes de "callbacks" no ambiente Sandbox, um endpoint foi desenvolvido na API pública com o objetivo de simular os eventos que serão recebidos posteriormente pelos callbacks.
O endpoint desenvolvido foi: “/v1/callbacks/generacion/evento”. O mesmo recebe as seguintes informações no body para realizar a simulação. A estrutura é a seguinte:

{
“codigoAviso”: “string”,
“codigoInmobiliaria”: “string”,
“configuracionCallback”: {
“authorizationHeaderKey”: “string”,
“authorizationHeaderValue”: “string”,
“lenguajeCallbackBody”: “EN”,
“url”: “string”
},
“contactEmail”: “string”,
“contactMessage”: “string”,
“contactName”: “string”,
“contactPhone”: “string”,
“publicationPlan”:”string”,
“tipoDeEvento”: “CONTACTO”
}

Os códigos das imobiliárias e dos ímóveis enviados devem ser reais no ambiente Sandbox. Como explicado anteriormente, existem 4 tipos de eventos a serem recebidos pelo callback. Isso deve ser especificado no campo "tipoDeEvento" do body, dependendo do evento, existem outros campos que são obrigatórios ou não. Se enviado o tipo de evento CONTACTO_MENSAJE, as informações de contato são obrigatórias, ou seja, o nome, telefone, e-mail e mensagem. No caso de CONTACTO, só é necessário o e-mail. Esses testes permitem que os integradores simulem a recepção de um callback e, dessa forma, testem o correto funcionamento do mesmo.

  • Para testar os retornos de chamada do tipo CREDITO o seguinte endpoint foi desenvolvido
O endpoint desenvolvido foi: “/v1/callbacks/generacion/evento/credito”. O mesmo recebe as seguintes informações no body para realizar a simulação. A estrutura é a seguinte:

{
“accion”: “ALTA”,
“codigoEmpresa”: “string”,
“configuracionCallback”: {
“authorizationHeaderKey”: “string”,
“authorizationHeaderValue”: “string”,
“lenguajeCallbackBody”: “EN”,
“url”: “string”
},
“planDePublicacion”: “string”,
“siteId”: “string”,
“status”: “HABILITADO”
}

No ambiente de produção, podem realizar um teste mais profundo com eventos reais, os callbacks devem ser configurados (siga as etapas de Configuração no início desta página) e associar um callback de teste, obtendo um cliente de amostra e monitorando com mais detalhes.

BRA