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/configuracao/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:// ou https://
  • authorizationHeaderKey: Chave para adicionar ao cabeçalho como autorização. É opcional e, por padrão, Authorization.
  • 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, a chave no cabeçalho será Authorization.
  • lenguajeCallbackBody: Idioma para o body do callback. 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 integracion@navent.com 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:// ou 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/configuracao/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/configuracao/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/configuracao/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


    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 Escrita, 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).
    • Usuário logado clicou 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/geracao/eventos". 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",
    "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/geracao/eventos". 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.