DET - Documento de Especificação Técnica dos Serviços Web Api

O sistema TCE-Docs deverá disponibilizar serviços Web Api para possibilitar a integração da interface do Add-ins JS for Windows e para integrar com o projeto E-TCE (sistema de processo eletrônico do TCE).

São restrições para a implementação e uso dos serviços Web Api do projeto TCE.Docs:

• A implementação do serviço será realizado no padrão .Net Web Api usando o .Net Framework 4.6.1 e o Swagger Framework Swashbuckle Core;
• Para a utilização dos serviços será necessário comunicar via protocolo HTTPS, utilizando o certificado do do TCE-Go para a comunicação segura;
• Os serviços será necessário autenticar no serviço para que a comunicação possa ocorrer via Token de acesso do usuário.

A estória de usuário que representa a necessidade acima apresentada é a estória:

Para especificar e documentar os serviços Web Api, foi utilizada a ferramenta Swagger On-line Editor para a criação do arquivo api_rest_tce-docs_v-1-0-0.yaml, que contem a especificação do serviço no padrão Swagger.

Na especificação dos serviços foram organizados em grupos das entidades de controle, as quais são: ModeloDocumento (Modelo de Documento), Usuario (Usuário), TipoDocumento (Tipo de Documento), Documento, e IndicadorPersonalizado (Indicador Personalizado).

Os serviços Web Api identificados estão listados na imagem que se segue, e nas subseções abaixo:

No serviço do grupo de Modelo de Documentos foram especificados os serviços para integração com a interface Add-in for JS Word, para a criação e manutenção do arquivos de modelo Word (.dotx). Para utilizar esse serviços será requisito a autenticação do usuário via token, o qual está especificado na seção 4.2.

Na chamada do serviço para salvar o Modelo de Documento, além de informa na requisição o objeto ModeloCompleto, informando os dados do modelo (ID, Descrição, Data de Criação e as Seções contendo seus Meta Indicadores), também deverá ser enviado no corpo do documento, o documento Word a ser salvo e relacionado a entidade Modelo de Documento do sistema TCE.Docs.

A clonagem de Modelo de Documento será uma operação que irá realizar a atualização do conteúdo do Modelo de Documento em edição para o conteúdo do modelo que está sendo clonado, bem como a adição das seções e dos indicadores de modelo na configuração do Modelo de Documento em edição.

Nessa operação caso exista seção cuja descrição seja a mesma, dentre as seções do modelo em edição quando comparada com as seções do modelo clonado, os indicadores da seção clonada serão adicionado a seção com mesma descrição, para que o usuário possa configurar da forma que desejar, através do plugin Add-ins JS for Word.

Esse serviço será consultado o Modelo de Documento a partir do ID informado na requisição do serviço. Caso o usuário requisitante tenha acesso ao modelo de documentos informado, o sistema irá retornar os dados do documento e do corpo da resposta será enviado o arquivo do documento Word para ser editado pelo usuário.

Através desse serviço serão consultadas as seções com os indicadores de modelo do documento de ID informado na requisição.

Utilizando esse serviço será possível obter a imagem de um indicador de modelo do tipo de dado 11-Imagem, através do ID da imagem, a qual deverá ser informada na requisição da chamada do serviço. O conteúdo (array de bytes) da imagem será retornado no corpo da resposta, e o nome do arquivo será informado no cabeçalho da resposta.

Nessa consulta, o serviço espera receber um objeto que contem os filtros de consulta a partir da descrição e de duas datas que juntas representam o período de cadastro do modelo de documento que o usuário deseja buscar. Como retorno desse serviço será uma lista de objetos de Modelo de Documento simplificado, no qual contem apenas o ID, a descrição e a data de criação dos modelos localizado com base nos filtros informados.

Esse serviço de Login será utilizado para obter o token de acesso do usuário. Na requisição será informado as credenciais do usuário de acesso ao sistema TCENet, informando o usuário e a senha de acesso. Na resposta da autenticação, caso o usuário e senha informados sejam válidos, será retornado no cabeçalho da resposta o token de acesso informado na variável de nome access_token, bem como o tipo de autenticação que deverá ser usada nas requisições dos demais serviços que exigem a autenticação via token, que será informado na variável de nome token_type. O tempo de vida do token será retornado também no cabeçalho da resposta, através da variável maxAge.

Através desse serviço será validado se o usuário autenticado com o token de acesso informado na requisição, tem acesso de edição do arquivo de ID informado, que poderá ser tanto um arquivo de Modelo de Documentos Word, quando um arquivo de documento Wrod (.docx).

Atingido o tempo máximo de vida do token de acesso do usuário, antes de executar qualquer outra requisição, deverá ser invocado o serviço de atualização do token, o qual será atualizado, gerando assim um novo token que será retornado no cabeçalho da resposta, da mesma forma como apresentado na seção 4.2.1 referente a utilização do serviço de Login.

Através de desse serviço será consultado os tipos de documento que o usuário autenticado pelo token informado na requisição tem acesso. Dessa forma, será retornada uma lista de Tipos de Documento localizados, contendo o ID do tipo de documento e sua descrição.

O serviço de criação de documento, receberá por parâmetro as seguintes informações:

• ID do Tipo de Documento;
• ID do Assunto Processual; e
• Um dicionário de informações de modelo;

Com base no ID do Tipo de Documento, do ID do Assunto Processual e do Setor/Usuário identificado pelo token de acesso, o sistema TCE.Docs deverá buscar uma Configuração de Documento que atenda a esses parâmetros informados. Nessa consulta será esperado apenas uma configuração que a tenda aos parâmetros informados, caso haja localizado mais de uma configuração, essa validação será reportada ao usuário através do retorno de HTTP Status Code igual a 422, informando ao mesmo a anomalia identificada orientando o usuário a informar ao suporte do sistema, visto que esse cenário não é esperado.

Localizada uma Configuração de Documentos, o sistema irá utilizar as informações de modelo informadas na requisição para compor os indicadores de modelo da configuração, de modo a informar na criação do documento, ainda no servido, os indicadores de modelo que serão atualizados no conteúdo do documento, para então possa ser salva a primeira versão do documento para então ser enviada ao requisitante do serviço para então iniciar a sua edição.

Esse serviço será utilizado para que o sistema TCE.Docs possa registrar um novo andamento no ciclo de vida do documento, no qual será informado na requisição o ID do documento que será registrado o andamento, o ID do descritor da situação do documento, e o usuário que irá receber o documento para dar continuidade no ciclo de vida do documento.

Através desse serviço, será gerada a numeração para o documento de ID informado na requisição, caso o mesmo tenha uma configuração de controle de numeração configurado para o Tipo de Documento do Documento. Caso a numeração seja gerada, além de vincular a numeração ao documento, como documentado no DET de Controle de Numeração, a numeração gerada será retornada na resposta da requisição.

O serviço de consulta de documento irá consultar o documento a partir do ID do documento informado na requisição, caso seja localizado o documento será retornado no corpo da resposta em forma de Stream.

Nesse serviço será consultadas as seções com os indicadores de dados do documento de ID informado na requisição.

Através serviço será consultadas os valores já preenchidos para os indicadores de dados do documento ID informado na requisição.

Utilizando esse serviço será possível consultar Indicador Personalizado, a partir da descrição e do tipo de indicador (1-Dado, 2-Modelo) informado por parâmetro na requisição do serviço. Dessa forma, será retornado uma lista de Indicadores Personalizados localizados.