Callbacks

La funcionalidad de callbacks les permite a los integradores recibir notificaciones de eventos vinculados a acciones realizadas sobre los avisos y sobre leads (contactos) ya integrados en Navent Real Estate a través de Open Navent.

Configuración

La configuración de los Callbacks se puede realizar de dos formas, una a través de soporte y otra de forma autónoma con el endpoint PUT /v1/configuracion/callbacks.

Para ambas configuraciones se debe brindar la misma información:

  • url: URL POST donde se realizará el callback. Es obligatorio enviar la url y debe comenzar con http:// o https://
  • authorizationHeaderKey: Key para agregar al header como autorización. Es optativo y por defecto Authorization.
  • authorizationHeaderValue: Valor con token o cadena encriptada para la autorización del callback. Si este valor está asignado, pero authorizationHeaderKey no tiene valor, entonces el key en el header será Authorization.
  • lenguajeCallbackBody: EN para inglés, ES para español, PT para portugués. Optativo.

Si opta por configurar a través de soporte, se debe enviar un mail a [email protected] con la información anteriormente mencionada.

Si opta por configurar a través del endpoint, este recibe un objeto con los campos mencionados. Cabe destacar que la URL es Obligatoria y debe comenzar con http:// o https://. El key de la autorization se envía en el header de la request POST en el callback. Por ejemplo para aplicar Basic Authorization de HTTP. Si es Basic Authorization debe enviar todo el token completo, es decir con la palabra Basic incluída.

Ejemplo:
Basic b3BlbjpjYWxsYmFja3M=

Para verificar si la configuracion fue correcta, en cualquiera de los dos casos, se puede utilizar el endpoint GET /v1/configuracion/callbacks, el cual devuelve el mismo objeto que fue enviado en el PUT, con la información que fue configurada.

Suscripción a los eventos de Callbacks

Una vez se haya configurado el servicio de callback se debe suscribir a todos los eventos de los cuales desea obtener notificaciones, para esto debe hacer uso del siguiente endpoint:

PUT /v1/configuracion/callbacks/{evento}

Los eventos disponibles son los siguientes:
  • CONTACTO
  • CONTACTO_MENSAJE
  • AVISO_CALIDAD
  • AVISO_ACTIVIDAD
  • AVISO_ESTADO_PUBLICACION
  • CREDITO

 

También tendrán a la disposición un endpoint el cual les va a permitir desuscribirse de todos los eventos de los cuales no desean recibir notificaciones:

DELETE /v1/configuracion/callbacks/{evento}

Si no se suscribe a ningún evento de callbacks por defecto no le llegaran los notificaciones sobre sus propiedades

Diferencias en Status Responses

Todo callback será exitoso al momento de llamarse mientras NO reciba como response un código 4xx o 5xx (puede ser cualquiera de los posibles status 400 o cualquiera de los posibles 500), es decir que todos los 2xx o 3xx (nuevamente pueden ser cualquiera de los posibles 200 o cualquiera de los posibles 300) son aceptados. Mientras el sistema de callbacks pueda llegar al endpoint, la respuesta será exitosa.

Se esperará respuesta como máximo de 1.5 segundos. Si no se recibe respuesta en ese tiempo, nuestro sistema interpreta que hubo un timeout y, por lo tanto, un error. En este caso se volverá a reintentar realizar el Callback como cualquier proceso de error, hasta que el Callback llegue a destino o pasen 72 hs desde la creación del Callback. Después de las 72 hs el estado de Callback pasa a VENCIDO.

 

SUGERENCIA: es buena práctica validar que un Callback no fue entregado al cliente verificando el ID del evento.
Eventos

Los eventos que se notifican a través de callbacks son:

  • Cambio de estado en un aviso
  • Alta/baja de un aviso
  • Usuario logueado consultó por el teléfono de la inmobiliaria en la publicación
  • Mensaje de un posible cliente a través del portal
  • Leads de usuarios Anónimos (la API Pública no los muestra). Por ejemplo, cuando el usuario haga click en “Ver Teléfono” sin estar logueado en el portal.
  • Cambio de calidad de un aviso
  • Alta, baja o modificacion de los creditos de una inmobiliaria

Según el tipo de integración los eventos son notificados a través de callbacks o no. Las integraciones de Lectura y Escritura, reciben notificación de todos los eventos. En cambio, las de Solo Lectura solo reciben notificaciones de leads, es decir, la consulta de teléfono y la del mensaje a través del portal.

Diferencias a tener en cuenta

Cuando se consultan leads: AVISO_ESTADO_PUBLICACION notificará al usuario si un aviso cambio el estado de su publicación, es decir cuando el mismo pase de online a offline o viceversa. En cambio, AVISO_ACTIVIDAD, además de cumplir con la anterior funcionalidad, informará al usuario si el aviso consultado ha sido modificado.

Eventos por tipo de evento

Anteriormente se mostró la lista de eventos que competen tanto a los avisos como a los desarrollos, pero en este punto intentaremos dar una explicación un poco más explicativa, haciendo referencia a los tipos de evento que desencadena cada evento

  • Cualquier modificación en el body de un aviso (se notificará en AVISO_ACTIVIDAD).
  • Alta/baja de un aviso (se notificará en AVISO_ACTIVIDAD y AVISO_ESTADO_PUBLICACION).
  • Usuario logueado consultó por el teléfono de la inmobiliaria en la publicación (se notificará en CONTACTO).
  • Mensaje de un posible cliente a través del portal (se notificará en CONTACTO_MENSAJE).
  • Leads de usuarios Anónimos (la API Pública no los muestra). Por ejemplo, cuando el usuario haga click en “Ver Teléfono” sin estar logueado en el portal (se notificará en CONTACTO).
  • Modificación de calidad de una aviso: (se notificará en AVISO_CALIDAD).
  • Alta,baja o modificación de los planes de publicación de una inmobiliaria (se notificará en CREDITO).
Body Callbacks

El envío de información del sistema de callbacks es por región/idioma. En la request al callback configurado se enviará esta información a través del body. El body depende de los eventos y de la región en la que se encuentra el integrador o el lenguaje configurado.

En la sección de body callbacks, se pueden observar el cuerpo de las posibles respuestas.

¿Cómo realizar el testing?
  • Para poder realizar pruebas de callbacks en el ambiente de Sandbox, se desarrolló un endpoint en la API-Pública con el objetivo de simular los eventos que luego serán recibidos por callbacks.
El endpoint desarrollado es: “/v1/callbacks/generacion/evento”. El mismo recibe en el body la siguiente información para poder realizar la simulacion. La estructura es la siguiente:

{
“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”
}

Los códigos de la inmobiliaria y del aviso enviados deben ser reales en el ambiente de Sandbox. Como se explicó con anterioridad, hay 4 tipos de eventos a recibir por callbacks. Este debe ir especificado en el campo “tipoDeEvento” del body, dependiendo del evento hay otros campos que son requeridos o no. Si se envia el tipo de evento CONTACTO_MENSAJE, la informacion de contacto es obligatoria, es decir, el nombre, teléfono, mail y mensaje. En el caso de CONTACTO, solo es necesario el email. Estas pruebas les permiten a los integradores poder simular la recepción de un callback y, de esta manera probar el correcto funcionamiento de los mismos.

  • Para probar los callbacks de tipo CREDITO se desarrollo el siguiente endpoint
El endpoint desarrollado es: “/v1/callbacks/generacion/evento/credito”. El mismo recibe en el body la siguiente información para poder realizar la simulacion. La estructura es la siguiente:

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

En el ambiente de producción, pueden realizar una prueba más profunda con eventos reales, se deberían configurar callbacks (seguir los pasos de Configuración al comienzo de esta misma página) y asociar un callback de prueba, tomando un cliente de muestra y realizar un seguimiento más detallado.

ARG