Ferramentas do usuário

Ferramentas do site


controle_acesso:orientacoes_ws

Orientações para Integração com o SIOP via WEB-Services

Este documento é destinado aos usuários e desenvolvedores de sistemas que integrarão com o SIOP via WS. Ele dá os detalhes de como é o processo de aquisição de credenciais, configuração e como acessar os ambientes de testes e produção do SIOP por WEB-Service.

Para entendimento geral de como é o controle de acesso ao SIOP, seja por login de usuário ou acesso WS, vide Manual de Controle de Acesso.

1. Acesso aos WEB-Services do SIOP

1.1 Contexto

O SIOP, Sistema de Planejamento e Orçamento Federal, suporta os processos orçamentários no âmbito federal, dotando os agentes envolvidos de ferramentas operacionais e gerenciais que apoiam e facilitam a tomada de decisão. No entanto, muitas UO e OS possuem sistemas internos (conhecidos também como IntraSigs) próprios, já consolidados, que também fazem o planejamento e gestão do orçamento de forma integrada às suas atividades finalísticas. Desse fato surgiu a necessidade de se criar um mecanismo que possibilite a interoperação entre os IntraSigs e o SIOP, a fim de aproveitar o que é feito nas UO e OS, otimizar o esforço e a utilização dos recursos disponíveis, mas respeitando os processos internos de cada instituição.

Órgão Gestor

Sigla: SOF
Razão Social: Secretaria de Orçamento Federal
Código SIORG: 2032

1.2 O que são WEB-Services?

Aplicação lógica, programável que torna compatíveis entre si os mais diferentes aplicativos, independentemente do sistema operacional, permitindo a comunicação e intercâmbio de dados entre diferentes redes. (glossário do e-ping)

1.3 O que é necessário para acessar os WEB-Services do SIOP

A Portaria SOF n. 130 reconhece o acesso ao SIOP via WS e define que ele terá procedimentos específicos que serão divulgados pela SOF:

O item 2.2 da portaria sofreu alteração. Maiores informações sobre suporte técnico ao sistema SIOP podem ser obtidas diretamente no site do Sistema, www.siop.planejamento.gov.br ou www.siop.gov.br.

O requisito para acesso ao serviço é possuir uma credencial cadastrada no SIOP. A credencial é composta pelo login do usuário, senha e perfil WS com o qual se deseja executar as operações. Além disso, a aplicação que for consumir os WS do SIOP deve configurar os devidos certificados para se comunicar com o WS do SIOP.

Os detalhes para tal cadastro e configuração estão no documento de Orientações para acesso aos WS do SIOP.

2. Processo de Credenciamento para Uso dos WS do SIOP

Após entendimento do uso dos WS do SIOP, o pedido de acesso ou alteração de responsável pelo WS pode ser feito pelo preenchimento do formulário e sua entrega para a Central de Atendimento SIOP. Esta entrega pode ser feita pessoalmente na SOF ou enviando o pedido (devidamente preenchido e assinado) em formato já digitalizado para a central de atendimento. Maiores informações sobre suporte técnico ao sistema SIOP podem ser obtidas diretamente no site do Sistema, www.siop.planejamento.gov.br ou www.siop.gov.br.

O pedido será analisado e após sua tramitação interna na SOF, se tudo estiver certo, a central de Atendimento retornará ao Responsável Técnico pelo WS por telefone ou email. O SIOP enviará automaticamente as informações de sua credencial para o email do responsável técnico. Caso haja problemas com o pedido, a central retornará informando o fato.

Em caso de mudança nas informações do formulário para um determinado sistema cliente, tais como a mudança do Responsável Técnico, será necessário retificar o cadastro enviando novo formulário devidamente assinado com a indicação de que se trata de uma retificação.

2.1 Preenchimento do Formulário de Cadastro para uso do WS do SIOP

O passo inicial para acesso aos WS do SIOP é preencher o Formulário de Cadastro para Utilização do Webservice SIOP.

Seguem orientações para o preenchimento do formulário:

1 - DADOS DO RESPONSÁVEL TÉCNICO PELO ACESSO Contato entre a SOF e a equipe técnica do órgão (pode ser externa ao órgão). Pode ser da área de negócios ou da TI. As informações de CPF e Email serão usadas para o cadastro da credencial no SIOP. Este é o contato para os chamados de suporte e demais comunicações técnicas.
Formulário para retificaçãoMarcar “Sim” se este formulário for alterar informações previamente cadastradas (não criará uma nova credencial)
2 - DADOS DO TITULAR DA UNIDADE Os dados são do representante da área de negócio que autoriza o órgão a usar o WS do SIOP. Normalmente do titular da área de orçamento.
3 - DADOS DO SISTEMA CLIENTE Nome do sistema que irá acessar o SIOP - este nome será usado para compor a informação de login do WS a ser enviado pela SOF
IP's de saida para a internet - é preciso que a área de TI do órgão informe esses dados para que seja feita a liberação da entrada no firewall da SOF.
4 - TERMO DE RESPONSABILIDADE SOBRE OS RECURSOS ASSINALADOS É necessária a assinatura do Responsável Técnico e do Titular da Unidade. Se o certificado for de um terceiro, é necessária a assinatura deste.

Todos os campos acima são obrigatórios!. Os formulários incompletos serão devolvidos.

OBS: note que um usuário (CPF) pode ter acesso ao SIOP e seu CPF também ter credencial para acesso aos WEB-Services do SIOP. Neste caso, cada acesso tem um conjunto de privilégios distinto pois o acesso ao WS é o acesso de um sistema, dado pelo seu nome no login ao WS do SIOP.

3. Uso de Certificados

O uso do WS do SIOP exige configurações de certificados no sistema cliente. O sistema do cliente, tanto em ambiente de testes como de produção, deverá confiar na cadeia de certificados ICP-Brasil, pois o certificado digital do SIOP é emitido por esta organização.

A infraestrutura do SIOP já atualizou a cadeia para as versões mais novas.

Para acessar o WS de produção do SIOP então é necessário configurações de informações de 2 certificados no cliente:

  1. Certificado do SIOP
  2. Certificado do cliente

3.1 Certificado ICP-Brasil do SIOP

Como dito antes, o certificado do servidor SIOP para o webservice.siop.gov.br é do ICP-Brasil. Tanto no ambiente de testes como no de produção é necessário que o cliente confie no certificado apresentado pelo servidor SIOP.

A implementação dessa relação de confiança varia, o que depende da tecnologia de desenvolvimento utilizada, mas normalmente se faz importando o certificado do servidor no repositório de certificados de servidores conhecidos (na truststore, no exemplo de um cliente Java). Ou seja, você está dizendo ao seu programa que ele deve confiar no webservice.siop.gov.br sem emitir qualquer alerta.

Validade do certificado: os certificados dos nossos servidores têm validade de apenas 1 ano, o que demanda a atualização anual na truststore do cliente.

3.1.1 Obtenção do Certificado do SIOP

Certificado Atual do SIOP

Atual (expira 23-01-2020)certificados_webservices_siop.zip


3.2 Certificado Próprio

Deve ser adquirido pelo usuário um Certificado Digital ICP-Brasil - tipo A1, que é emitido por uma Autoridade Certificadora pertencente a ICP-Brasil. Este certificado, após emitido, deve ser configurado (importado) no repositório de “certificados de cliente” (keystore, no caso do java). Ou seja, é o certificado que o usuário apresentará ao SIOP para autenticar a sua conexão com a SOF, de forma unívoca.

Para solicitação e emissão do certificado será necessário seguir as orientações da sua Autoridade Certificadora - AC. As orientações para os usuários da Autoridade Certificadora SERPRO podem ser encontradas no seguinte endereço: https://ccd.serpro.gov.br/serproacf/

Observação: segundo o Ofício Circular n. 825 de 15 de dezembro de 2016, o MP não custeia mais ou emite certificados para sistemas estruturantes ou integrantes do SISP.

Os seguintes atributos são necessários no certificado:

  • CN - URL identificadora da aplicação ou equipamento (ex: www.orgao.gov.br)
  • O - ICP-Brasil
  • OU - Equipamento A1

Campos obrigatórios do responsável pelo certificado, definidos pela ICP-Brasil para certificados de equipamento/aplicação:

  • e-mail institucional
  • CPF
  • RG

Caso os dados do responsável não correspondam ao titular da unidade administrativa, este deverá, por meio de documento específico (formulário acima), nomear o responsável pelo certificado. Esses atributos, associados ao CN, deverão ser os mesmos cadastrados e autorizados no SIOP como usuário de serviço, para acesso do web service cliente.

Note que o próprio certificado do cliente também tem validade e que precisará ser substituído na keystore do cliente após o seu vencimento. Do contrário, não será validado pelo servidor. O mesmo pode ocorrer com o certificado da CA emitente. Se o certificado da CA vencer, o certificado final do cliente não será aceito, mesmo que não esteja vencido.

Transação HTTPS/TLS para acesso ambiente de Testes do SIOP - Handshake simples (somente com certificado do SIOP)

Transação HTTPS/TLS para acesso ambiente de Produção do SIOP - Handshake completo (com certificados do cliente e do SIOP)

Para mais informações sobre certificados: http://pt.wikipedia.org/wiki/Certificado_digital

Exemplo: como importar o novo certificado no Firefox

Para fins de teste, o certificado pode ser instalado no firefox, na aba servidores, em opções→avançado→certificado→servidores. Situação 1: o certificado do cliente está instalado no browser:

  1. Acessar a URL webservice.siop.gov.br/services/WSQualitativo?wsdl, por exemplo
  2. Clicar com o botão esquerdo no cadeado e clicar em “mais informações”
  3. Na aba segurança, clicar em exibir certificado. Clicar na aba detalhes, selecionar o certificado webservice.siop.gov.br e clicar em exportar (em formato PEM)
  4. Importar o arquivo PEM na lista de certificados confiáveis do cliente do webservice

Situação 2: o certificado do cliente NÃO está instalado no browser e NÃO foi adicionada a exceção de segurança relativa ao novo certificado do servidor:

  1. Acessar a URL webservice.siop.gov.br/services/WSQualitativo?wsdl, por exemplo
  2. Neste caso, quando o browser apresentar a tela de “adicionar exceção”, clicar em“exibir” o certificado, clicar na aba detalhes, selecionar o certificado e clicar em exportar (em formato PEM)
  3. Importar o arquivo PEM na lista de certificados confiáveis do cliente do webservice

Situação 3: o certificado do cliente NÃO está instalado no browser e JÁ foi adicionada a exceção de segurança relativa ao novo certificado do servidor:

  1. Acessar a URL webservice.siop.gov.br/services/WSQualitativo?wsdl, por exemplo
  2. Clicar em Ferramentas > opçoes → Avançado > certificados → certificados
  3. Na aba servidores… o certificado webservice.siop.planejamento.gov.br estará sob ICP-Brasil
  4. Selecionar o certificado webservice.siop.gov.br e clicar em exportar (exportar no formato PEM)
  5. Importar o arquivo PEM na lista de certificados confiáveis do cliente do webservice

4. Credenciais WS SIOP

Os acessos WS ao SIOP são controlados por vários mecanismos de segurança. A identificação de um sistema cliente WS é dada por uma credencial. Cada credencial é dada para um sistema específico.

Uma credencial do SIOP é um usuário especial do sistema que tem permissões de acesso WS. Uma credencial é composta de um nome de login, normalmente iniciado por “WS” e uma senha. Estas informações serão usadas para autenticar o acesso ao SIOP por meio de WS.

Note que as credenciais de WS não permitem o acesso ao ambiente como usuários (pessoas). Não se pode logar manualmente no SIOP usando estas credenciais1).

O processo de entrega da credencial para o usuário técnico responsável é todo automático e descrito nestas instruções. Neste serviço as credenciais podem ser alteradas pelo próprio sistema cliente do SIOP.

Como o WS SIOP deve receber a informação da credencial:

  • O usuário é o login da credencial cadastrada no SIOP (normalmente WS-nome_do_sistema - não é o CPF do responsável!).
  • O valor passado no atributo senha deve ser o hash MD5 da mesma. Não pode ser nulo.

4.1 Perfis WS do SIOP

Para cada acesso será necessário especificar um perfil2).

Segue abaixo a tabela de perfis WS do SIOP:

Código Nome do perfil WS O perfil será aprovado por
106 WebService - Cadastrar Precatório SOF
34 WebService - DEST SOF
105 WebService - Gestão PPA SPI
111 WebService - Gestão PPA - Preenchedor SPI
33 WebService - Órgão Central SOF
32 WebService - Orgão Setorial SOF
31 WebService - Unidade Orçamentária SOF

Observação: muitos casos de uso de WS do SIOP envolvem envio de dados, como por exemplo propostas para o PLOA ou captação do Acompanhamento Orçamentário. Neste caso o envio para o SIOP somente se dará pelo uso do perfil OS ou superior pois o sistema somente aceitará envios para estes momentos. Para maiores informações veja o manual específico do WS SIOP em questão.

5. Ambientes de WS no SIOP

Os WS são baseados em tecnologia aberta WEB como SOAP, XML e WSDL. Os endereços WS para acesso aos ambientes assim como seu propósito estão abaixo:

Testes https://testews.siop.gov.br/services/NOME_WS?wsdl É usado somente o certificado do servidor SIOP
Produção https://webservice.siop.gov.br/services/NOME_WS?wsdl Além do certificado do SIOP, exige o certificado do cliente também

Onde NOME_WS deve ser alterado para o WS em questão.

Os ambientes podem ser acessados por interface web também. Podem ser usados para validar ou conferir operações WS:

Testes https://testews.siop.gov.br/siop/ Obs: a base de dados deste ambiente não é igual à de produção
Produção mesmo endereço do SIOP produção Dados de produção do SIOP

Obs: pode haver diferença nas versões e nos dados de testes e produção em uso pelos ambientes. As atualizações dependem de que serviços estão sendo testados ou avaliados no momento. Informe-se se a funcionalidade sendo testada no ambiente de testes pode ter diferenças para a versão de produção. No caso de consultas (apenas leitura), não há problemas em testar a funcionalidade em produção, porém será necessário o certificado ICP-Brasil válido do cliente.

Para iniciar o uso dos WS do SIOP, acesse os manuais específicos de WS SIOP.

6. Suporte e Contato

Os manuais de cada WS do SIOP dão mais detalhes do uso de cada WS. Eles podem ser encontrados na página inicial dos manuais.

Em caso de dúvidas, sugestões ou comentários por favor, entre em contato por meio do Portal de Serviços (https://portaldeservicos.planejamento.gov.br/).

Observação Importante

Somente o Responsável Técnico identificado no formulário enviado (e posteriormente aprovado) poderá requerer intervenções na credencial e outras ações relacionadas com os privilégios de sua credencial no SIOP.

1) Mais detalhes podem ser encontrados no Manual de Controle de Acesso ao SIOP
2) Para detalhes sobre perfis do SIOP acesse Privilégios no SIOP - Perfis e Papéis