Requerimientos básicos para el desarrollo de una integración técnica

A través de una integración puedes conectar Virtual Assistant con otro servicio externo.

Para avanzar con la integración, será necesario que nos compartas toda la información requerida sobre el servicio con el que deseas integrarte, ya sea propio o de un tercero, actualizada al momento de realizar el desarrollo.

Esto incluye documentación técnica, accesos, metodologías, protocolos, requisitos de seguridad y cualquier otro detalle necesario para su implementación.

Los pasos generales a seguir una vez que informes qué servicio necesitas integrar son:

1. Te enviaremos los requerimientos específicos necesarios para realizar la integración.
2. Deberás compartir estos requerimientos con tu equipo técnico o con el proveedor del servicio involucrado.
3. Una vez relevada la información, deberás enviarnos la documentación y los datos solicitados para su análisis.
4. Tras la validación correspondiente, avanzaremos con la implementación y ejecución de la integración.

Esta información nos permitirá evaluar la viabilidad de la integración y definir los pasos necesarios para llevarla adelante.

Tipos de integración y sus requisitos 

➡️ Integraciones mediante Web Service

Las integraciones mediante Web Service permiten compartir información con otros sistemas e intercambiar datos sin necesidad de conocer los detalles de sus respectivos sistemas de información.

 Conoce ¿Qué es un Web Service?  

Puedes integrarte con cualquier tipo de Web Service, independientemente de la tecnología de envío y recepción de datos que uses (REST o SOAP). 

1. Tiempo de implementación: el desarrollo de un Web Service demora, en promedio, una semana. El plazo puede extenderse según la complejidad de cada caso, por ejemplo, si requiere métodos de autenticación o configuración de VPNs. 
2. Modos de uso en Virtual Assistant: 
   1. Proactivo: en cuanto el usuario inicia una conversación, el asistente le ofrece un listado de opciones disponibles. No es necesario que haga una consulta específica para que se active.
   2. Por demanda: el usuario activa la integración al consultar algo que la dispara.

➡️ Integraciones con APIs de terceros

Virtual Assistant permite cualquier tipo de integración con APIs de terceros. La documentación debe presentarse preferiblemente en Postman, con suficientes detalles y ejemplos. Puedes ver un ejemplo aquí: Documentación API 

⬇️ A continuación, te contamos qué información necesitamos para poder desarrollar una integración desde Aivo Engageware. 

1. La pregunta que desencadenará la integración. 
2. Las rutas, endpoints o servicios que se usarán para dar una respuesta. 
   1. Datos de servicios de terceros: cada servicio a consultar debe estar asociado a un endpoint e incluir:
      1. Parámetros de entrada. 
      2. Parámetros de salida. 
      3. Descripción de cada parámetro. 
      4. Formato de envío y recepción. 
      5. Endpoint que consume el servicio y parámetros de headers o métodos a consumir. 
   2. La documentación puede presentarse en alguno de los siguientes formatos: donde se listan las posibles opciones de APIs: 
      1. Postman Collection (recomendado) 
      2. Swagger 
      3. Apiary 
      4. RAML 
3. Escenarios posibles: es importante documentar cada uno de los escenarios por los que pasará el usuario. Te recomendamos usar diagramas de flujo que muestren el paso a paso, con todos los casos posibles, sus respuestas y los endpoints consultados en cada etapa. 
4. Los datos que debemos usar desde Aivo Engageware en cada escenario, para poder realizar las pruebas. 
   1. Un ejemplo de cada endpoint como comando curl. 
   2. La respuesta esperada de cada servicio en todos los casos. 
   3. Todos los posibles mensajes de error que puede devolver el servicio, con una explicación y una posible solución para cada uno. 
   4. Casos y parámetros de prueba que permitan confirmar todos los escenarios posibles. 

ℹ️ Información adicional: Para evitar demoras en el desarrollo, también necesitamos saber: 

1. Tipos y formatos de datos a enviar y recibir: JSON, Arrays, XML.
2. Seguridad de red: si cuentas con algún nivel de seguridad de red, será necesario habilitar IPs. Crear VPNs. 
3. Ambiente de pruebas: ¿Dispones de un ambiente de test? ¿Es estable? En caso de caídas, ¿en cuánto tiempo se estima que puede recuperarse? 
4. Autenticación: si los servicios requieren autenticación, indica: 
   1. El tipo de autenticación que se usará. 
   2. Las credenciales de los ambientes disponibles.

✅ Factores a tener en cuenta: 

1. En algunos casos, los servicios de terceros necesitan configuraciones específicas para aceptar el acceso de Virtual Assistant. 
2. Es importante que cada proveedor mantenga los servicios activos y con los accesos disponibles al momento de realizar las pruebas. 
3. La documentación no puede enviarse en formato Excel. 

 Ejemplos de documentación a recibir

Endpoint por servicios a través de Swagger: La documentación debe estar organizada por flujo. Por cada flujo, debe incluir todos los endpoints del servicio con: los datos a enviar y recibir, el concepto y función de cada servicio, los tipos de datos enviados y recibidos, y para qué se usa cada uno.

1. Swagger permite indicar el método de envío y el complemento del endpoint.

2. Las notas de lo que va a recibir el servicio.

3. La respuesta que se debe recibir del servicio.

4. El JSON a enviar o formato de envío.

5. El tipo de parámetros a enviar si se desea cargar y no pasar por estructura.

6. Los distintos mensajes que se recibirán, Curl, endpoint, response body, etc.

7. El swagger permite realizar pruebas directamente ya sea ingresando los datos o a través del JSON enviado.

 > Por último, se muestra un diagrama de flujos como ejemplo, donde se observa el proceso de cancelación de citas de principio a fin, con cada uno de los posibles casos, toma de decisiones y servicios a consultar en cada etapa. Esto facilita tener una visión completa del procedimiento y las validaciones a realizar para todos los equipos involucrados.