Requisitos básicos para o desenvolvimento de uma integração técnica

Por meio de uma integração, você pode conectar o Virtual Assistant a outro serviço externo.

Para avançar com a integração, será necessário que você nos compartilhe todas as informações exigidas sobre o serviço com o qual deseja se integrar, seja próprio ou de terceiros, atualizadas no momento do desenvolvimento.

Isso inclui documentação técnica, acessos, metodologias, protocolos, requisitos de segurança e qualquer outro detalhe necessário para sua implementação.

Os passos gerais a seguir assim que você nos informar qual serviço precisa integrar, são:

1. Enviaremos os requisitos específicos necessários para realizar a integração.
2. Você deverá compartilhar esses requisitos com sua equipe técnica ou com o fornecedor do serviço envolvido.
3. Após o levantamento das informações, você deverá nos enviar a documentação e os dados solicitados para análise.
4. Após a validação correspondente, avançaremos com a implementação e execução da integração.

 Essas informações nos permitirão avaliar a viabilidade da integração e definir os passos necessários para realizá-la.

Tipos de integração e seus requisitos

➡️ Integrações via Web Service

As integrações via Web Service permitem compartilhar informações com outros sistemas e trocar dados sem precisar conhecer os detalhes de seus respectivos sistemas de informação.

 Veja O que é um Web Service?

Você pode se integrar a qualquer tipo de Web Service, independentemente da tecnologia de envio e recebimento de dados que utilizar (REST ou SOAP).

1. Tempo de implementação: o desenvolvimento de um Web Service demora, em média, uma semana. O prazo pode se estender conforme a complexidade de cada caso, por exemplo, se exigir métodos de autenticação ou configuração de VPNs.
2. Modos de uso no Virtual Assistant:
   1. Proativo: assim que o usuário inicia uma conversa, o assistente oferece uma lista de opções disponíveis. Não é necessário que ele faça uma consulta específica para que seja ativado.
   2. Por demanda: o usuário ativa a integração ao fazer uma consulta que a aciona.

➡️ Integrações com APIs de terceiros

O Virtual Assistant permite qualquer tipo de integração com APIs de terceiros. A documentação deve ser apresentada preferencialmente no Postman, com detalhes e exemplos suficientes. Veja um exemplo aqui: Documentação API

 Veja a seguir quais informações precisamos para desenvolver uma integração pela Aivo Engageware.

1. A pergunta que acionará a integração.
2. As rotas, endpoints ou serviços que serão usados para dar uma resposta.
   1. Dados de serviços de terceiros: cada serviço a consultar deve estar associado a um endpoint e incluir:
      1. Parâmetros de entrada.
      2. Parâmetros de saída.
      3. Descrição de cada parâmetro.
      4. Formato de envio e recebimento.
      5. Endpoint que consome o serviço e parâmetros de headers ou métodos a consumir.
   2. A documentação pode ser apresentada em um dos seguintes formatos:
      1. Postman Collection (recomendado)
      2. Swagger
      3. Apiary
      4. RAML
3. Cenários possíveis: é importante documentar cada um dos cenários pelos quais o usuário passará. Recomendamos usar diagramas de fluxo que mostrem o passo a passo, com todos os casos possíveis, suas respostas e os endpoints consultados em cada etapa.
4. Os dados que devemos usar pela Aivo Engageware em cada cenário para realizar os testes.
   1. Um exemplo de cada endpoint como comando curl.
   2. A resposta esperada de cada serviço em todos os casos.
   3. Todas as possíveis mensagens de erro que o serviço pode retornar, com uma explicação e uma possível solução para cada uma.
   4. Casos e parâmetros de teste que permitam confirmar todos os cenários possíveis.

Informações adicionais: para evitar atrasos no desenvolvimento, também precisamos saber:

1. Tipos e formatos de dados a enviar e receber: JSON, Arrays, XML.
2. Segurança de rede: se você tiver algum nível de segurança de rede, será necessário habilitar IPs e criar VPNs.
3. Ambiente de testes: você tem um ambiente de teste? É estável? Em caso de instabilidade, em quanto tempo estima que pode ser recuperado?
4. Autenticação:se os serviços exigirem autenticação, informe:
   1. O tipo de autenticação que será usado.
   2. As credenciais dos ambientes disponíveis.

 Fatores a considerar:

1. Em alguns casos, os serviços de terceiros precisam de configurações específicas para aceitar o acesso do Virtual Assistant.
2. É importante que cada fornecedor mantenha os serviços ativos e com os acessos disponíveis no momento de realizar os testes.
3. A documentação não pode ser enviada em formato Excel.

➡️ Exemplos de documentação a receber

Endpoint por serviços via Swagger: a documentação deve estar organizada por fluxo. Para cada fluxo, deve incluir todos os endpoints do serviço com: os dados a enviar e receber, o conceito e a função de cada serviço, os tipos de dados enviados e recebidos, e para que cada um é usado.

1. O Swagger permite indicar o método de envio e o complemento do endpoint.

2. As notas sobre o que o serviço receberá.

3. A resposta que deve ser recebida do serviço.

4. O JSON a enviar ou o formato de envio.

5. O tipo de parâmetros a enviar, caso se queira carregá-los sem passá-los pela estrutura.

6. As diferentes mensagens que serão recebidas: Curl, endpoint, response body, etc.

7. O Swagger permite realizar testes diretamente, seja inserindo os dados ou por meio do JSON enviado.

8. Por fim, é apresentado um diagrama de fluxos como exemplo, onde se observa o processo de cancelamento de agendamentos do início ao fim, com cada um dos casos possíveis, as tomadas de decisão e os serviços a consultar em cada etapa. Isso facilita ter uma visão completa do procedimento e das validações a realizar para todas as equipes envolvidas.