Informações sobre a integração com o SIAFI
Para viabilizar a integração de sistemas externos ao SIAFI web, os responsáveis pelos sistemas externos devem seguir os seguintes passos:
1º Passo: Conhecer previamente a tecnologia utilizada
A oferta de serviços do SIAFI Web via APIs/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 SIAFI Web, todos os gestores dos sistemas que desejam se integrar ao SIAFI Web devem ter domínio sobre o uso das tecnologias listadas acima.
Todos os serviços ofertados pelo SIAFI Web estão aderentes à 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: Conhecer o catálogo de serviços do Siafi Web
Acesse essa página para conhecer os serviços disponíveis.
3º passo: Gerar um certificado digital de equipamento
Para estabelecimento de uma conexão segura entre o SIAFI Web 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 abaixo 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 do SIAFI Web)
[Windows + Keystore explorer 5.0.1]
• Produção: (Utilizado para acesso ao ambiente de Produção do SIAFI Web – PR).
[Windows + Keystore explorer 5.0.1]
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 SIAFI Web, por meio da transação CONSISORIG (ver 4º passo).
4º passo: Cadastrar o certificado gerado no SIAFI Web
Os órgãos que quiserem que seus sistemas se integrem ao SIAFI Web via Web Services devem utilizar a transação INCSISORIG (Incluir Sistema de Origem) do SIAFI Web 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 SIAFI Web.
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 SIAFI Web
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 SIAFI Web para o ambiente e ano desejado conforme descrito no catálogo de serviços do SIAFI Web.
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, devem procurar o cadastrador no seu órgão e solicitar sua habilitação. 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 SIAFI Web, 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 SIAFI Web 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[MMFL1] (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[MMFL2] (compatível com a Documentação de Serviços de Interoperabilidade - Manter Programação Financeira - Versão [2.8]).
Orientações sobre os XSD (XML Schema Definition)
Para as operações disponíveis somente por webservice, a forma de obter os xsds deve ser através da url do WSDL do serviço, onde constam as demais urls dos XSDs que ele referencia/importa através da propriedade schemaLocation.
URL do WSDL:
https://homextservicos-siafi.tesouro.gov.br/siafi2019he/services/cpr/manterContasPagarReceber?wsdl
Exemplo :
No wsdl há uma referência ao XSD do Bilhetador:
<xsd:import namespace="http://www.tesouro.gov.br/bilhetador/xsd/bilhetador" schemaLocation="https://homextservicos-siafi.tesouro.gov.br/siafi2019he/services/cpr/manterContasPagarReceber?xsd=../../bilhetador/NovoSIAFI-Bilhetador.xsd"/>
Acessando a URL indicada no schemaLocation é possível visualizar o XSD do Bilhetador.
https://homextservicos-siafi.tesouro.gov.br/siafi2019he/services/cpr/manterContasPagarReceber?xsd=../../bilhetador/NovoSIAFI-Bilhetador.xsd
Este é o caminho mais correto, pois ocorrerem mudança nos serviços, o Sistema Externo conseguirá sempre obter a versões mais recentes dos XSDs através da url.
Importante observar que, como o ambiente HE (homologação externa) é um ambiente que requer autenticação com certificado, para conseguir acessar a url do WSDL no browser, precisa ter o arquivo .p12 do certificado importado no browser, ou seja, dever ser o mesmo certificado importado na CONSISORIG.
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 então utilizar um válido com cadeias oficiais das ARs-Autoridades certificadoras. Para a acesso ao ambiente de Produção, são aceitas apenas cadeias oficiais das ARs. 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 SIAFI Web?
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 SIAFI Web 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.