Integração Web Service

Um Web Service é uma aplicação lógica programável acessível via protocolos Web. O Web service do MGV7 também funciona com o Windows Communication Foundation (WCF) que é um framework para construir aplicações orientadas a serviços. Usando WCF, você pode enviar mensagens assíncronas de um serviço a outro. Este serviço pode ser parte de um serviço hospedado no ISS ou pode ser um serviço hospedado em uma aplicação. O serviço pode ser um cliente de um outro serviço que busca dados de outro serviço. As mensagens podem ser simples caracteres ou palavras mandadas em XML, ou dados complexos, como stream de dados ou dados binários.

Configuração:

Após habilitar o uso do WebService na opção "Definir funcionalidades e cadastros disponíveis", no painel de controle será exibido o ícone "Configuração da integração com WebService".
Ao abrir a janela, é necessário definir:

• Host: Computador responsável pela comunicação.
• Palavra Chave: Senha utilizada para a conexão com o serviço.
• Porta: porta de comunicação que será utilizada.
• Protocolo:
  • HTTP(REST/SOAP)
  • TCP
  • HTTPS (Para ajuda ao configurar esse protocolo, consulte Como Configurar Protocolo HTTPS)


• Tipo de Autenticação:
• Básica - Utiliza somente a palavra chava para autenticação.
• Usuário e Senha - Utiliza usuário e senha para autenticação. O usuário informado deve estar cadastrado no MGV7 e seu perfil deve possuir a permissão de "Utilização do web service".
• Certificado Digital - Utiliza um certificado digital para autenticação. Somente está disponível para o protocolo HTTPS.
• Bearer Token - Utiliza um token para autenticação. O usuário informado deve estar cadastrado no MGV7 e seu perfil deve possuir a permissão de "Utilização do web service".


• TimeOut: Tempo de espera para a resposta, em minutos - mínimo 10 minutos
• Link para WebService: Link montado automaticamente ao preencher as informações acima. Utilizado para consultar se o WebService está ativo.

Para informações sobre os métodos existentes, consulte aqui

Para a utilização do tipo de protocolo HTTP, com chamadas REST , basta no final no link do webservice adicionar a palavra /REST.
Exemplo:
http://192.168.0.1/MGV7_WCF/REST

Como Configurar Protocolo HTTPS

Para realizar a configuração do protocolo HTTPS, é necessário que a máquina possua um certificado digital válido instalado. Esse certificado pode ser auto-assinado ou adquirido de uma autoridade certificadora.
Para criar um certificado digital auto-assinado em um computador com Windows, abra o Power Shell como administrador e digite o seguinte comando, substituindo [INSERIR NOME DO SERVIDOR AQUI] pelo nome do servidor:

$cert = New-SelfSignedCertificate -certstorelocation cert:\localmachine\my -dnsname [INSERIR NOME DO SERVIDOR AQUI]

Isso criará um certificado digital auto-assinado e o instalará no repositório de certificados do computador. Para visualizar o certificado, procure por "Gerenciar certificados de computador" no menu iniciar e navegue até "Certificados - Computador Local" > "Pessoal" > "Certificados". O certificado criado estará listado lá, conforme imagem a baixo:





Com um certificado em mãos, é necessário obter seu thumbprint. Para isso, clique duas vezes sobre o certificado, entre na aba "Detalhes", procure por "Impressão Digital" e copie o valor. Esse valor será utilizado na configuração do WebService. A imagem a seguir mostra um exemplo dessa janela:



Com a impressão digital do certificado digital em mãos, acesse a tela de "Configuração da integração com WebService" e selecione o protocolo HTTPS e preencha o campo "Digital do Certificado" com o valor copiado anteriormente.



Observação: Ao utilizar um certificado auto-assinado, é necessário configurar o client para aceitar certificados não confiáveis. Caso contrário, mensagens de erro como "Error: SSL peer certificate or SSH remote key was not OK" ou "SSL Error: Unable to verify the first certificate" serão exibidas.

Configuração e Utilização de Cada Tipo de Autenticação

• Básica
  A autenticação básica é a forma mais simples de autenticação. Ela utiliza a palavra chave configurada no WebService para autenticar o usuário. Para utilizá-la, basta preencher o campo "Palavra Chave" na tela de "Configuração da integração com WebService" e selecionar "Básica" no campo "Tipo de Autenticação".
  A palavra chave somente será validada em requisição que possuem o campo adequado para ela (como, por exemplo, o endpoint "IniciaImportacao").



• Usuário e Senha
  A autenticação por usuário e senha utiliza um usuário cadastrado no MGV7 para autenticar a requisição. Para utilizá-la, selecione a opção de "Usuário e Senha" no campo "Tipo de Autenticação".
  O usuário informado deve estar cadastrado no MGV7 e seu perfil deve possuir a permissão de "Utilização do web service" para que a permissão seja concedida.
  
  
  
  Com um usuário válido cadastrado e com a permissão correta, é necessário informar o usuário e a senha na requisição. O usuário e senha devem ser informado no Header de Authorization, sob a categoria de "Basic", conforme exemplo a seguir:
  
  



• Certificado Digital (Somente Disponível ao Utilizar Protocolo HTTPS)
  A autenticação por certificado digital utiliza um certificado digital instalado no servidor para autenticar a requisição. Para utilizá-la, selecione a opção de "Certificado Digital" no campo "Tipo de Autenticação".
  Dentro de cada requisição feita ao webservice, é necessário enviar o certificado digital na mesma. O servidor então conferirá se o certificado enviado é confiado pelo mesmo. Dessa forma, é necessário que o certificado digital esteja instalado no servidor dentro do repositório de Autoridades de Certificação Raiz Confiáveis. Caso um certificado seja adicionado ou removido do repositório, o serviço da carga remota deve ser reiniciado.
  Para instalar um certificado auto-assinado no repositório de Autoridades de Certificação Raiz Confiáveis, basta clicar duas vezes sobre o certificado, ir na aba "Detalhes", clicar em "Copiar para arquivo..." e seguir o assistente de exportação, exportando a chave privada. Após isso, basta clicar duas vezes sobre o arquivo .pfx gerado e seguir o assistente de instalação, certificando-se de selecionar o repositório de "Autoridades de Certificação Raiz Confiáveis".
  Uma vez que o certificado está instalado na máquina de host, é necessário configurar a requisição para enviar esse mesmo certificado. No PostMan, por exemplo, é necessário acessar as Configurações > Certificados e configurar um certificado com o arquivo .pfx. A imagem e legenda abaixo ilustra como cada campo deve ser preenchido:
  
  
  
  Onde:
  1. Endereço do computador onde esse certificado será utilizado. Na prática, será o valor configurado no campo "Host" das configurações de integrações com o webservice
  2. Porta de comunicação que será utilizada. Na prática, será o valor configurado no campo "Porta" das configurações de integrações com o webservice
  3. Arquivo .pfx do certificado. Deve conter o mesmo certificado instalado na máquina de host.
  4. Senha do arquivo .pfx do certificado.
  
  Observação: Também é possível utilizar um arquivo .crt e .key, ao invés de um arquivo .pfx e sua senha. Para isso, basta preencher os campos "Arquivo .crt" e "Arquivo .key" com os arquivos correspondentes e suas respectivas senhas.



• Bearer Token
  A autenticação via Bearer Token utiliza um token para autenticar a requisição. Para utilizá-la, selecione a opção de "Bearer Token" no campo "Tipo de Autenticação".
  Para gerar um token, é necessário que o usuário esteja cadastrado no MGV 7 e seu perfil possua a permissão de "Utilização do web service". Com essas permissões, é possível gerar um token de acesso através do endpoint GetToken do webservice. O token gerado será válido por 30 minutos e deve ser enviado no Header de Authorization, sob a categoria de "Bearer", conforme exemplo a seguir:
  
  
  
  Observação: O token gerado deixará de ser válido caso o serviço da carga remota seja reiniciado.