WebServices

A integração via Web Services é uma inovação do Novo SIAFI sem paralelo no SIAFI Mainframe. Trata-se da possibilidade de que potencialmente qualquer sistema se integre diretamente ao Novo SIAFI através da troca de mensagens.

Ao contrário da Integração via Arquivos Batch, este meio de integração tem reflexos imediatos no SIAFI, ou seja, qualquer requisição feita será processada e uma resposta será enviada ao sistema cliente no mesmo momento. Outra característica é que este meio de integração está disponível apenas durante o mesmo período no qual o próprio sistema está acessível ao usuário na Web.

A natureza síncrona desta forma de integração a torna mais apropriada para sistemas que necessitem de uma comunicação interativa com o SIAFI. Por outro lado, implica também na impossibilidade de processar um volume muito grande de dados de uma única vez.

Para viabilizar a integração de sistemas externos ao Novo SIAFI, os responsáveis pelos sistemas externos devem seguir os seguintes passos:


1º Passo: CONHECER PREVIAMENTE A TECNOLOGIA UTILIZADA

A oferta de serviços do Novo SIAFI via webservices se fundamenta basicamente em três tecnologias:

  • - Web Services Description Language (WSDL): Define a interface de acesso ao serviço;
  • - Simple Object Access Protocol (SOAP): Um protocolo baseado em XML. Permite que os clientes se comuniquem com os provedores de serviço;
  • - Universal Description, Discovery and Integration (UDDI): Permite Web services registrarem suas características, permitindo que outras aplicações as encontrem.

Independentemente da tecnologia escolhida para implementação do sistema cliente dos serviços do Novo SIAFI, todos os gestores dos sistemas que desejam se integrar ao Novo SIAFI devem ter domínio sobre o uso das tecnologias listadas acima.

Todos os serviços ofertados pelo Novo SIAFI estão aderentes àa arquitetura e-PING (Padrões de Interoperabilidade de Governo Eletrônico) que define um conjunto mínimo de premissas, políticas e especificações técnicas que regulamentam a utilização da Tecnologia de Informação e Comunicação (TIC) no governo federal, estabelecendo as condições de interação com os demais Poderes e esferas de governo e com a sociedade em geral.


2º passo: CONHECENDO O CATÁLOGO DE SERVIÇOS DO NOVO SIAFI

Os gestores dos sistemas que desejam estabelecer uma conexão via webservices com o Novo SIAFI devem primeiramente verificar se o serviço desejado encontra-se disponível no catálogo do Governo Eletrônico. A oferta de serviços é ampla mas não abrange totalmente as funcionalidades da versão on-line do Novo SIAFI.

O endereço para acesso à documentação de interoperabilidade do novo SIAFI é:

http://catalogo.governoeletronico.gov.br/.

Adicionalmente, também disponibilizamos em nossa página os documentos de interoperabilidade do Novo SIAFI para download:
 


3º passo: GERANDO UM CERTIFICADO DIGITAL DE EQUIPAMENTO

Para estabelecimento de uma conexão segura entre o Novo SIAFI e o sistema cliente, faz-se necessário o estabelecimento de uma Autenticação Mútua entre os sistemas que criará um canal seguro para troca de informações. Deve ser usado o protocolo https para efetuar transações online seguras. 
 
Para estabelecimento desse canal seguro o sistema cliente deverá possuir um certificado de Equipamento-A1 assinado por uma das autoridades certificadoras da ICP-Brasil.
 
Veja aqui os roteiros padrões (baseados em um ambiente Linux utilizando OpenSSL e Keytool) para solicitar certificados de:
 
Homologação: (Utilizado para acesso ao ambiente de Homologação Externa – HE e Homologação PCASP – HP do Novo SIAFI)   
 
Produção:  (Utilizado para acesso ao ambiente de Produção do Novo SIAFI – PR). 
 
Importante! 
O certificado de equipamento do tipo A1 tem validade de 1 ano. Então, todo ano os sistemas clientes precisarão gerar um novo certificado para o sistema externo (3o. passo). Este novo certificado deverá ser cadastrado no Novo SIAFI, por meio da transação CONSISORIG (ver 4º passo). 
 

 

4º passo: CADASTRAR O CERTIFICADO GERADO NO NOVO SIAFI

Os órgãos que quiserem que seus sistemas se integrem ao Novo SIAFI via Web Services devem utilizar a transação INCSISORIG (Incluir Sistema de Origem) do Novo SIAFI para cadastrar seus sistemas.

Para realizar o cadastro, as seguintes informações devem ser fornecidas:

  • • Sigla do sistema cliente;
  • • Sigla do Órgão ao qual o sistema pertence;
  • • Nome do Sistema (Tradução da SIGLA juntamente com informações que julgar pertinente);
  • • Informações para contato;
  • • Arquivo do Certificado Digital de Equipamento-A1 do sistema cliente no formato padrão X509, como por exemplo com extensão ".cer", ".crt", ".p7b", ".pem".

Para mais detalhes sobre a transação INCSISORIG, acessar o endereço: http://manualsiafi.tesouro.gov.br/administracao-do-sistema/web-service/manter-sistema-origem

Após a inclusão do sistema cliente, o certificado digital de máquina já poderá ser utilizado para constituir um canal de confiança com autenticação mútua por HTTPS entre o sistema cliente e o Novo SIAFI.

Importante: Os sistemas clientes cadastrados pelo órgão podem ser consultados e alterados na transação CONSISORIG. Para mais detalhes desta transação, acessar o endereço: http://manualsiafi.tesouro.gov.br/administracao-do-sistema/web-service/consisorig-consultar-sistema-de-origem.

Observação:
É recomendado que o órgão só cadastre o sistema cliente no ambiente de Produção após cadastrar o sistema no ambiente de homologação e realizar os testes necessários. É de responsabilidade do Órgão as informações geradas no ambiente de Produção e também é de sua responsabilidade que as mesmas estejam corretas. O ambiente de Homologação é disponibilizado justamente para que todos os testes sejam feitos antes do envio de dados reais.

Ambiente de Homologação => https://homext-siafi.tesouro.gov.br
Ambiente de Produção => https://siafi.tesouro.gov.br/

 

5º passo: TESTAR A COMUNICAÇÃO COM O NOVO SIAFI

O gestor do sistema cliente deve verificar se é possível criar o canal seguro através da autenticação mútua. Para isso deverá seguir os seguintes passos:

1 - Importar no browser o arquivo '.pfx' (PKCS #12 ) que possui a chave pública, privada e cadeias da autoridade certificadora que assinou o certificado (esse aquivo é gerado no 3º Passo desse roteiro). O arquivo 'pfx' define um formato de arquivo para armazenar vários objetos de criptografia em um único arquivo. Para realizar a importação no browser o usuário deve acessar a área de criptografia do browser e importar o arquivo '.pfx' na aba 'seus certificados'.

2 - Acessar a URL do WSDL do Novo SIAFI para o ambiente e ano desejado conforme descrito no catálogo de serviços do Novo SIAFI disponível em http://catalogo.governoeletronico.gov.br/.

Para testes de comunicação o Tesouro Nacional recomenda a utilização do navegador Mozilla Firefox.

No firefox: vá em Editar -> Preferências -> Avançado -> Criptografia -> Certificados -> Seus certificados -> importar.

Depois acessar uma das URLs abaixo de acordo com o ambiente cujo acesso foi solicitado:

Homologação:
https://homextservicos-siafi.tesouro.gov.br/siafi<ano>he/services/cpr/manterContasPagarReceber?wsdl

Produção:
https://servicos-siafi.tesouro.gov.br/siafi<ano>/services/cpr/manterContasPagarReceber?wsdl

onde <ano> é o ano do exercício. Ex: 2014.

Caso o WSDL seja aberto pelo browser, o cadastro foi realizado com sucesso. Caso contrário, acesse o nosso portal de Serviços através do link https://sisstn.tesouro.gov.br/eservicos-ext/#/public/homeUsuario/Area/1, escolha a opção WEBSERVICES e abra um chamado para análise do problema.

 

6º passo: SOLICITAR UM USUÁRIO SIAFI

 

O Órgão deverá providenciar que seus usuários sejam cadastrados no SIAFI no respectivo sistema de destino (Produção e/ou Homologação) para envio das requisições, caso não tenham.

Aqueles que ainda não tem acesso ao SIAFI, entretanto, precisam fazer a solicitação através do Formulário de Cadastro. O processo para solicitação de acesso ao SIAFI está melhor descrito em Cadastro e Habilitacao. Importante ressaltar que a concessão de acesso a cada um dos ambientes (Homologação e Produção) é feita separadamente e o usuário deve solicitar o acesso para todos os sistemas aos quais precise utilizar.

Cada mensagem emitida pelo sistema cliente terá que conter os dados de autenticação de um usuário também habilitado no SIAFI. Sendo assim, todas as requisições serão associadas não somente ao sistema cliente, mas também a um usuário com CPF no SIAFI.

Por este motivo, além do cadastro do sistema externo, é necessário que os usuários deste sistema estejam também cadastrados no SIAFI e com o perfil de acesso de acordo com as transações que serão utilizadas via webservices. Este cadastro é exatamente o mesmo necessário para o sistema online e quem já possui acesso à interface web não precisa solicitar nova habilitação.

 


7º. passo: IMPLEMENTAR SOLUÇÃO CLIENTE


Depois que o sistema estiver cadastrado e a comunicação tiver sido testada, haverá uma etapa de homologação na qual o sistema terá acesso não ao ambiente de produção do Novo SIAFI, mas a um ambiente específico de testes (Homologação) no qual o sistema poderá estabilizar a integração sem comprometer os dados de produção.

Para homologar a comunicação e as funcionalidades do sistema cliente, a STN disponibiliza o ambiente de Homologação para este fim.

Observação: A STN e o SERPRO não são responsáveis pela implementação do sistema cliente!


FUNCIONAMENTO

Qualquer sistema cliente devidamente habilitado pode enviar mensagens SOAP para a interface do SIAFI. Estas mensagens, se estiverem consistentes com a especificação de interface publicada, serão processadas e respondidas de maneira síncrona.

Para evitar que problemas de rede resultem em duplicidade de requisições, as mensagens sofrem controle de bilhetagem. Desta maneira, o Novo SIAFI não aceita reenvio de requisição se esta altera a base do sistema.

EXEMPLOS DE UTILIZAÇÃO

Mensagem de Inclusão de Documento Hábil (compatível com a Documentação de Serviços de Interoperabilidade - Manter Contas a Pagar e Receber - Versão [3.9]).

Mensagem de Inclusão de Programação Financeira (compatível com a Documentação de Serviços de Interoperabilidade - Manter Programação Financeira - Versão [2.8]).

 

ORIENTAÇÕES QUANTO AOS CAMPOS DO XML

Na construção do arquivo XML que será enviado para inclusão de um documento Hábil (web service Cadastrar Documento Hábil) existem alguns campos que, à primeira vista, são difíceis de identificar do que se tratam, como, por exemplo, os campos abaixo txInscrA, numClassA, txInscrB, numClassB, txInscrC e numClassC.

Isso porque quando o usuário está incluindo um documento hábil de forma on-line, o sistema apresenta esses campos com uma nomenclatura diferente, pois de acordo com a situação que o usuário escolheu, o sistema já sabe, pela tabela de situação (CONSIT), o que deve ser informado naquele campo. Porém, na inclusão por web-service, não temos como saber qual a situação, já que o leiaute é sempre o mesmo para todos os tipos de documentos hábeis e situações. Dessa forma, para saber o que informar nesses campos o usuário deve consultar no Siafi web a tabela de situações (CONSIT) e verificar, para o documento hábil e situação que pretende incluir, na aba ‘Configuração de campos', no item da tela ‘Campos Variáveis das abas', o que deve ser informado em cada campo, como exemplificado na tela abaixo.



Nesse caso, para a situação DSP001- AQUISIÇÃO DE SERVIÇOS - PESSOAS JURÍDICAS, no campo txIncrD deve ser informado o Código de Recolhimento de GRU.


PERGUNTAS FREQUENTES

Pergunta: O certificado de produção tem que ser gerado pelo SERPRO?
Resposta: Não. O certificado digital emitido deve conter cadeias de homologação ou oficiaisl para os ambiente Homologação do Novo SIAFI e cadeias de oficiais para o ambiente de Produção do Novo SIAFI. O certificado deverá ser do tipo A1 para equipamentos gerado por uma autoridade certificadora da ICP-Brasil.

Pergunta: Posso utilizar o e-CPF ou o e-CNPJ para cadastro no Novo SIAFI?
Resposta: Não. A exigência é que seja um certificado do tipo A1 Equipamento, assinado por uma autoridade certificadora da ICP-Brasil.

Pergunta: Eu preciso criar um certificado para cada ambiente/servidor que eu for instalá-lo?
Resposta: Não, apesar de ter esse nome de certificado de equipamento. O certificado é vinculado ao DNS da aplicação e poderá ser utilizado em mais de um servidor desde que seja para a mesma aplicação.

Pergunta: Após realizar o cadastro, o usuário tentou acessar a URL do WSDL do Novo SIAFI e o browser está solicitando login e senha ou então deu erro de handshake.
Resposta: Algum problema aconteceu no cadastramento do certificado digital. Acionar a STN para análise do problema.

Pergunta: Quem gera o certificado de homologação?
Resposta: Siga o roteiro para geração de certificado no seguinte link.