====== INFORMA - Manual de Integração ======
===== Introdução =====
Este documento tem por objetivo definir e especificar as interfaces de integração com serviços de recepção de dados do sistema INFORMA.
===== Considerações Iniciais =====
A Gerência de Tecnologia da Informação (GER-TI) juntamente com a Secretaria de Controle Externo, ambos do Tribunal de Contas do Estado de Goiás (TCE-GO), apresenta o módulo de serviços para integração ao sistema INFORMA.
Este trabalho foi realizado para atender uma demanda da Controladoria Geral do Estado que busca facilitar aos órgãos do poder executivo o envio de informações para o sistema INFORMA, dentre os requisitos temos:
* Integrar o sistema COMPRAS.Net ao INFORMA para o envio automático dos dados de licitação já cadastrados no primeiro sistema;
* Permitir o envio de informações parciais dos dados do formulário e posteriormente o usuário do sistema INFORMA de cada órgão, acessa este sistema, e finaliza o preenchimento dos dados que não vieram da integração;
* Agilizar o trabalho dos jurisdicionados, diminuindo retrabalho e integração total com os dados já cadastrados no sistema de gestão de licitação utilizados por eles.
==== Objetivo do Projeto ====
O objetivo deste projeto é automatizar o processo de envio de informações das licitações e contratações que os Jurisdicionados devem prestar ao TCE-GO. Para automatizar a recepção dos dados, foram implementados vários web services que permitirão à SEGPLAN (Secretaria de Gestão e Planejamento) integrar-se ao sistema INFORMA e enviar os dados cadastrados no sistema COMPRAS-Net.
O escopo inicial é atender a demanda de integrar-se ao sistema COMPRAS-Net, porém os jurisdicionados poderão utilizar deste recurso para envio de informações de outros sistemas de gestão de licitações. Pois há vários órgão que não utilizam o COMPRAS-Net.
===== Arquitetura de Comunicação com Jurisdicionado =====
==== Modelo Conceitual ====
O projeto Informa disponibilizará os seguintes serviços, os quais estão agrupados por interfaces de comunicação e escopo:
=== Web Service ===
i) Escopo do Formulário:
a) Consulta Órgãos ativos;
b) Consulta Formulários ativos;
c) Consulta lista de opções para os campos que tenham lista;
ii) Escopo da Informação:
a) Envio de informações;
b) Envio de arquivos para determinada informação;
c) Remoção de arquivos para determinada informação;
d) Envio da Informação para o Tribunal de Contas do Estado;
A comunicação via web service utilizará o protocolo HTTP com SSL (HTTPS) em ambas interfaces de comunicação, o usuário deverá se autenticar, este usuário e senha é unico e intransferivel e será encaminhado posteriormente. Todos os serviços Web Service estão disponíveis de forma síncrona e assíncrona.
==== Visão da Arquitetura de Comunicação ====
=== Web Service===
{{:pres:gerti:manuais:arquitetura_ws_informa.png|}}
Figura 3 - Visão Arquitetura de Comunicação via Web Service
=== Web Services ===
Os Web Services disponibilizam os serviços que serão utilizados inicialmente pelo aplicativo compras.net dentre outros, para o envio das informações de determinado formulário/Órgão. O mecanismo de utilização dos Web Services seguem as seguintes premissas:
a) É disponibilizado um Web Service por serviço, sendo eles o serviço de formulário (ServiceFormulario.svc) e o serviço de informação (ServiceInformacao.svc);
b) As URL dos Web Services encontram-se na seção Serviços e Web Service desse documento, juntamente com os respectivos WSDLs exportados;
c) O processo de utilização do Web Service sempre é iniciado pelo Jurisdicionado, enviando uma requisição de serviço utilizando o protocolo SOAP 1.2, com SSL e autenticação transportada na mensagem de requisição de serviço. O certificado de comunicação utilizado será o certificado do TCE-GO, que já é utilizado na autenticação do usuário pelo portal TCENet disponível no endereço web tcenet.tce.go.gov.br;
d) A ocorrência de qualquer erro na validação dos dados recebidos interrompe o processo, no retorno da mensagem de erro no FaultException, será informada a mensagem de validação ou erro de comunicação, para a devida correção pelo Jurisdicionado, podendo este entrar em contato com o setor de suporte de informática do TCE-GO para auxílio da resolução do problema identificado.
==== Serviços de Web Services ====
Os serviços de Web Service do projeto Informa foram desenvolvidos utilizando o protocolo SOAP 1.2, com transporte de mensagens utilizando a estrutura XML.
A autenticação da chamada será realizada com o envio na requisição de serviço as credenciais do Compras.Net, ou outro serviço devidamente autorizado, que são usuário e senha. Todo o canal de comunicação será encriptado utilizando protocolo seguro SSL com o certificado do TCE-GO.
Os Serviços de web services disponiveis estão relacionados e esclarecidos na proxima seção.
=== Serviço de Formulário (ServiceFormulario.svc)===
O serviço de formulários está disponível no endereço web https://informa-ws.tce.go.gov.br/ServiceFormulario.svc, o qual contem os métodos relatados abaixo.
Qualquer falha de validação ou falha inesperada, para todos os métodos descritos abaixo, será acionada uma exceção do tipo FaultException e na sua mensagem será informada qual o problema ocorrido e se possível a forma de resolve-lo.
== Consulta Órgãos Ativos (ConsultaOrgaosAtivos) ==
Ao invocar esté método o sistema devolverá um dicionário com todos os órgãos habilitados a receber informações via web service conforme tabela abaixo.
**Retorno da Consulta**
^Campo^ Tipo^ Descrição^
|Chave| long| Código do órgão|
|Valor| string| Texto com o nome do órgão.|
== Consulta formulário (ConsultaFormularios)==
Através desse método o usuário poderá consultar todos os formulários ativos para determinado órgão e categoria. Os valores a serem informados deve seguir a tabela abaixo.
^Campo^ Tipo^ Descrição^
|idOrgao |long |Código do órgão, obtido no método de consulta de orgãos|
|idCategoria |long |Código da categoria dos formulários, até o momento apenas o código 1 (TEXTO) está liberado.|
O retorno esperado é uma lista de DtoFormulário descrito na seção seguinte.
== Consulta opções das listas (ConsultaOpcoesDaLista)==
Através desse método o usuário poderá consultar todas as opções ativas para determinado campo. O valor a ser informado deve seguir a tabela abaixo.
^Campo^ Tipo^ Descrição^
|idCampo |long |Código do campo, obtido através da Consulta de Formulário, utilizado apenas para os campos do tipo Lista e ListaTabela|
|idCategoria |long |Código da categoria dos formulários, até o momento apenas o código 1 (Licitações e Contratações diretas) está liberado.|
O retorno esperado é um dicionario de chave/valor, onde a chave é o campo que deverá ser informado ao enviar uma informação e o valor e o texto é a descrição mostrada ao usuário durante o acesso normal ao Informa.
== WSDL==
O contrato WSDL desse serviço, que estabelece o mecanismo de comunicação está descrito abaixo:
https://localhost/TCE.Informa.WS/ServiceFormulario.svc/username
=== Serviço de Informação (ServiceInformacao.svc) ===
O serviço de informações está disponível no endereço web https://informa-ws.tce.go.gov.br/ServiceInformacao.svc, o qual contem os métodos relatados abaixo.
Qualquer falha de validação ou inesperada, para todos os métodos descritos abaixo, será acionada uma exceção do tipo FaultException, na qual conterá as informações de validação criticadas ou o erro inesperado e a forma de resolver o erro.
== Envia Informação (EnviaInformacao)==
Através deste método é possivel enviar a informação desejada e receber de volta o id da informação cadastrada. Os valores a serem informados deve seguir a tabela abaixo.
^Campo^ Tipo^ Descrição^
|idOrgao |long |Código do órgão, obtido no método de consulta de orgãos|
|dtoInformação |DtoInformacao|Objeto detalhado na seção seguinte.|
== Envia Arquivo (EnviaArquivo)==
Através deste método é possível enviar os arquivos relacionados a informação, sendo que está informação já deve ser sido enviada anteriormente, importante ressaltar que esta informação deve necessáriamente estar com o status “Em Elaboração”. Os valores a serem informados deve seguir a tabela abaixo.
^Campo^ Tipo^ Descrição^
|idOrgao |long |Código do órgão, obtido no método de consulta de orgãos|
|idInformacao |long |Código da informação em situação “Em Elaboração”|
|dtoArquivos |DtoArquivos |Objeto detalhado na seção seguinte.|
== Remove Arquivo (RemoveArquivo)==
Através deste método é possível remover os arquivos relacionados à informação enviada anteriormente. Os valores a serem informados deve seguir a tabela abaixo, caso a remoção seja realizada com sucesso o método retornará “verdadeiro” confirmando a remoção. Importante ressaltar que esta informação deve estar com o status “Em elaboração”.
^Campo^ Tipo^ Descrição^
|idOrgao |long |Código do órgão, obtido no método de consulta de orgãos|
|idInformacao |long |Código da informação em situação “Em Elaboração”|
|dtoArquivos |DtoArquivos |Objeto detalhado na seção seguinte.|
== Envia TCE (EnviaTce)==
Através deste método é possível marcar a informação como completa, “enviando” a mesma para o Tribunal de Contas do Estado e bloqueando a edição. Durante este processo todos os campos são verificados, quanto a obrigatoriedade, validação de CPF/CNPJ, validação de valor informado e o tipo esperado, entre outros.
^Campo^ Tipo^ Descrição^
|idOrgao |long |Código do órgão, obtido no método de consulta de orgãos|
|idInformacao |long |Código da informação em situação “EmElaboração”|
== WSDL==
O contrato WSDL desse serviço, que estabelece o mecanismo de comunicação está descrito abaixo:
https://localhost/TCE.Informa.WS/ServiceInformacao.svc/username
=== Objetos de transferência de dados ===
Os objetos de transporte utilizados nas requisições e retorno dos métodos dos serviços, descritos na seção anterior estão descritos abaixo:
**DtoFormulario**
a) Descrição:
Objeto que representa um formulário ativo, identificando suas seções e campos passíveis de recebimento da informação. Quando um nova versão do formulário para determinado tipo de formulário for lançada as informações abaixo podem ser atualizada, dada a natureza dinâmica de todo formulário, sempre é recomendado que se faça uma consulta dos formulários para se obter as seções e os campos atualmente aceitos para determinado formulário.
b) Propriedades:
i) Id*: Numero identificador do formulário.
ii) TipoFormularioId*: Numero identificador do tipo do formulário.
iii) Descricao: Nome do formulário que é apresentado para o usuário em tela.
iv) FormularioPaiId*: Numero identificador do formulário que precede este formulário, na hora de preencher a informação para este formulário. .
v) AceitaRetificacao: Identificador que determina se este formulário aceita ou não uma retificação, que significa a retificação de um formulário deste tipo já enviado ao TCE.
vi) Versao: Número da versão deste formulário, toda alteração na seções ou campos deste formulário fazem com que o mesmo tenha a sua versão incrementada.
vii) Sumario: O sumário contêm uma explicação, detalhada, do formulário.
viii) Secoes*: Contêm uma lista com todas as seções deste formulário. Este Dto é esclarecido abaixo.
* Campos obrigatórios para o Envio de um formulário.
**DtoSecao**
a) Descrição:
Objeto organizador dos campos que formam um formulário. É na seção que se identifica se os campos são usados apenas para uma retificação e se a seção é do tipo lista, aceitando mais de uma linha durante o envio da informação.
b) Propriedades:
i) Id: Numero identificador da seção.
ii) Ordem: Identifica qual a sua posição quando da exibição em tela do formulário.
iii) TipoSecao: Identifica qual o tipo da seção, através do Enumerador de Tipos de seção. Os tipos possíveis são: Fixo e Lista. Na opção Fixo o sistema espera receber apenas 1 valor para cada campo relacionado na lista de campos desta seção, já para a opção Lista, o sistema aceita o recebimento dos campos relacionados mais de uma vez, isto será descrito mais adiante.
iv) Retificacao: Identifica se esta seção é utilizada apenas em uma retificação ou não.
v) Campos: Lista com todos os campos desta seção. Este Dto é esclarecido abaixo.
**DtoCampo**
a) Descrição:
Objeto que contêm todas as informação de um campo, que será utilizado tanto para o Envio da Informação, como para a Consulta de um formulário.
b) Propriedades:
i) Id*: Identificador único do Meta Campo, que é obtido na Consulta de formulário e sempre deve ser informado ao enviar uma informação.
ii) Descricao: Descrição que é exibida ao usuário para preencher o campo. Ex.: “Nº do Processo”
iii) TipoDado*: Identifica qual o tipo de dado esperado neste campo do seção. As opções são descritas abaixo.
iv) Obrigatorio: Identifica se o campo é obrigatório, utilizado para dar feedback visual ao usuário durante o preenchimento de uma informação. O campo só será validado quando a obrigatoriedade quando for solicitado através do método “Envia ao TCE” passando-se o Id da Informação.
v) Ordem: Identifica qual é a posição do campo ao exibir para o usuário na tela.
vi) Sequencia*: Campo importante para o envio da informação. Este campo representa a linha de uma seção do tipo lista, devendo ser preenchido sequencialmente iniciando com 1. Para a seção do tipo fixa este valor não precisa ser preenchido.
vii) Valor*: Campo que representa o valor para o campo, apesar do campo aceitar uma sequência de caracteres, o campo será validado quanto ao seu tipo (item iii, acima), assim que a informação for enviada ao sistema.
viii) Md5Arquivo: Campo que representa a string de validação do tipo MD5 dos bytes de um arquivo. Para o campo do Tipo “Arquivo” será possível enviar no campo Valor uma URL, para que o webservice obtenha o mesmo da internet e valide o conteudo obtido com o MD5 informado neste campo, reduzindo assim o trafego de dados pela rede.
* Campos obrigatórios para o Envio de um formulário.
**EnumTipoDado**
a) Descrição:
Enumerador com todas as opções possíveis para o tipo do Campo.
b) Opções:
i) Texto (1) - Tipo texto.
ii) Numero (2) - Tipo long, sem casas decimais.
iii) ListaTabela (3) - Tipo lista tabela, refere-se a opções cadastradas em uma tabela do banco.
iv) Lista (4) - Tipo lista, com as opções cadastradas dentro do informa.
v) Arquivo (5) - Tipo Arquivo.
vi) Cpf (6) - Tipo CPF, será salvo sempre apenas os números do CPF.
vii) Cnpj (7) - Tipo CNPJ, será salvo sempre apenas os números do CNPJ.
viii) ValorMonetario (8) - Tipo valor monetário, será salvo sempre com duas casas decimais, exemplo: 2000,00
ix) Data (9) - Tipo data, no formato: DD/MM/YYYY
x) Hora (10) - Tipo hora, no formato: HH(24):MM
xi) DataHora (11) - Tipo Data e Hora, Armazena data e hora no formato: DD/MM/YYYY HH(24):MM.
xii) Boleano (12) - Tipo Boleano, 1 - SIM e 0 - NÃO.
xiii) Sexo (13) - Tipo Sexo.
xiv) CpfOuCnpj (14) - Tipo CPF ou CNPJ, sem formação.
**DtoArquivo**
a) Descrição:
Objeto que representa um campo do tipo arquivo.
b) Propriedades:
i) Id*: Identificador único do Meta Campo, que é obtido na Consulta de formulário e sempre deve ser informado ao enviar um arquivo.
ii) Sequencial*: pNúmero sequencial que será utilizado para ordenar os arquivos deste neste campo.
iii) NomeArquivo* - Nome do arquivo que será utilizado para mostrar ao usuário.
iv) Conteudo*: - Contéudo do arquivo em bytes.
* Campos obrigatórios para o Envio de um formulário.
**DtoInformação**
a) Descrição:
Objeto que representa uma informação, identificando suas seções e campos relacionados.
b) Propriedades:
i) Id*: Número do informação caso ela já tenha sido enviada anteriormente.
ii) FormularioId*: Identificação do formulário em que a informação estará relacionada.
iii) FormularioPaiId*: Caso a informação já tenha uma informação pai a mesma deve ser informada aqui, mantendo o relacionamento dos formulários Pais e Filhos.
iv) FormularioRetificadoId*: Caso a informação já tenha sido enviada e esta seja uma retificação a mesma deve ser informada neste campo.
v) Situacao*: Situação da informação no momento do envio, podendo ser “EmElaboração” ou “Enviada”,
vi) Secoes*: Contêm uma lista com todas as seções e os campos que serão inseridos nesta informação, conforme descrito anteriormente.
===== Considerações Finais. =====
Este documento apresentou os aspectos tecnológicos para integração ao sistema INFORMA e poderá ser utilizado por todos os jurisdicionados do TCE-GO.