====== WEB-Service do módulo Receitas ======

===== Informações Gerais =====

==== Serviço ====

| Nome: | Web Service do módulo Receitas do SIOP |
| Nome na interface: | WSReceita |
| Início da operação: | 13/05/2014 |
| Endereço do WSDL - Testes | https://testews.siop.gov.br/services/WSReceita?wsdl |
| Endereço do WSDL - Produção | https://webservice.siop.gov.br/services/WSReceita?wsdl |

==== Objetivo ====

Fornecer uma interface que possibilite a interoperabilidade entre os sistemas governamentais e o SIOP para a transmissão de dados referentes à captação de base externa para os cenários de arrecadação de receitas.



===== Operações =====

Nesta seção estão relacionadas as operações disponibilizadas pelo serviço. A figura abaixo ilustra como essas operações devem ser utilizadas na obtenção das informações necessárias para a construção da estrutura de dados que deve ser enviada para o SIOP.

{{ :webservices:wsreceita:ws_receitas_operacoes.png?700 |}}

==== Captar Base Externa ====

Operação para cadastro e de base externa.

**Nome da operação na interface do serviço:**
captarBaseExterna

**Parâmetro(s) de entrada:**
|Parâmetro|Tipo (tamanho)|Observações|
|credencial|CredencialDTO|Credencial do usuário|
|captacaoBaseExternaDTO|CaptacaoBaseExternaDTO| |

**Tipo de Retorno:**
RetornoCaptacaoBaseExternaDTO

**Exemplo:**

Requisição:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://servicoweb.siop.sof.planejamento.gov.br/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:captarBaseExterna>
         <credencial>
            <perfil>32</perfil>
            <senha>***</senha>
            <usuario>WSINFRASIG</usuario>
         </credencial>
         <captacaoBaseExterna>
            <codigoCaptacaoBaseExterna>466</codigoCaptacaoBaseExterna>
            <detalhesBaseExterna>
               <detalheBaseExterna>
	             <codigoNaturezaReceita>21230000</codigoNaturezaReceita>
                  <codigoUnidadeRecolhedora>26101</codigoUnidadeRecolhedora>
                  <subNatureza>149</subNatureza>
                  <justificativa>justificativa</justificativa>
                  <metodologia>metodologia</metodologia>
                  <memoriaDeCalculo>memoriaDeCalculo</memoriaDeCalculo>
                  <valoresBaseExterna>
                     <valorBaseExterna>
                        <exercicio>2014</exercicio>
                        <valor>444</valor>
                     </valorBaseExterna>
                  </valoresBaseExterna>
               </detalheBaseExterna>
            </detalhesBaseExterna>
         </captacaoBaseExterna>
      </ser:captarBaseExterna>
   </soapenv:Body>
   </soapenv:Envelope>

Resposta:

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sof="http://servicoweb.siop.sof.planejamento.gov.br/">
   <env:Header>
      <sof:request>A6A6342E22DF78A9F8B50364669F1F5D</sof:request>
   </env:Header>
   <env:Body>
      <ns2:captarBaseExternaResponse xmlns:ns2="http://servicoweb.siop.sof.planejamento.gov.br/">
         <return>
            <sucesso>true</sucesso>
            <captacoesBaseExterna>
               <captacaoBaseExterna>
                  <codigoCaptacaoBaseExterna>466</codigoCaptacaoBaseExterna>
                  <detalhesBaseExterna>
                     <detalheBaseExterna>
                        <codigoNaturezaReceita>21230000</codigoNaturezaReceita>
                        <codigoUnidadeRecolhedora>26101</codigoUnidadeRecolhedora>
                        <subNatureza>149</subNatureza>
                        <justificativa>justificativa</justificativa>
                        <metodologia>metodologia</metodologia>
                        <memoriaDeCalculo>memoriaDeCalculo</memoriaDeCalculo>
                        <valoresBaseExterna>
                           <valorBaseExterna>
                              <exercicio>2014</exercicio>
                              <valor>444.0</valor>
                              <usuarioInclusao>João da Silva</usuarioInclusao>
                           </valorBaseExterna>
                        </valoresBaseExterna>
                        <versao>0</versao>
                        <usuarioInclusao>João da Silva</usuarioInclusao>
                     </detalheBaseExterna>
                  </detalhesBaseExterna>
               </captacaoBaseExterna>
            </captacoesBaseExterna>
         </return>
      </ns2:captarBaseExternaResponse>
   </env:Body>
   </env:Envelope>

==== 2.2 Consultar Detalhes por Grupo de Natureza de Receita ====

Operação de exclusão de pedido de alteração orçamentária.

**Nome da operação na interface do serviço:**
consultarDetalhesPorGrupo

**Parâmetro(s) de entrada:**
|Parâmetro|Tipo(tamanho)|Observações|
|credencial|CredencialDTO|Credencial do usuário|
|codigoCaptacaoBaseExterna|Integer| |
|grupoNaturezaReceita|String(5)| |

**Tipo de Retorno:**
RetornoCaptacaoDetalheBaseExternaDTO

**Exemplo:**

Requisição:

   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://servicoweb.siop.sof.planejamento.gov.br/">
      <soapenv:Header/>
      <soapenv:Body>
         <ser:consultarDetalhesPorGrupo>
            <credencial>
               <perfil>32</perfil>
               <senha>***</senha>
               <usuario>WS-SISTEMA</usuario>
            </credencial>
            <codigoCaptacaoBaseExterna>466</codigoCaptacaoBaseExterna>
            <grupoNaturezaReceita>40000</grupoNaturezaReceita>
         </ser:consultarDetalhesPorGrupo>
      </soapenv:Body>
   </soapenv:Envelope>

Resposta:

  <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sof="http://servicoweb.siop.sof.planejamento.gov.br/">
   <env:Header>
      <sof:request>F610A7F31A51EAEE8648CEB1EDB02D70</sof:request>
   </env:Header>
   <env:Body>
      <ns2:consultarDetalhesPorGrupoResponse xmlns:ns2="http://servicoweb.siop.sof.planejamento.gov.br/">
         <return>
            <sucesso>true</sucesso>
            <detalhesCaptacaoBaseExterna>
               <detalheCaptacaoBaseExterna>
                  <codigoNaturezaReceita>22120102</codigoNaturezaReceita>
                  <codigoUnidadeRecolhedora>74101</codigoUnidadeRecolhedora>
                  <subNatureza>160</subNatureza>
               </detalheCaptacaoBaseExterna>
               <detalheCaptacaoBaseExterna>
                  <codigoNaturezaReceita>16000201</codigoNaturezaReceita>
                  <codigoUnidadeRecolhedora>74101</codigoUnidadeRecolhedora>
                  <subNatureza>159</subNatureza>
               </detalheCaptacaoBaseExterna>
               <detalheCaptacaoBaseExterna>
                  <codigoNaturezaReceita>16000201</codigoNaturezaReceita>
                  <codigoUnidadeRecolhedora>74101</codigoUnidadeRecolhedora>
                  <subNatureza>173</subNatureza>
               </detalheCaptacaoBaseExterna>
               <detalheCaptacaoBaseExterna>
                  <codigoNaturezaReceita>16000201</codigoNaturezaReceita>
                  <codigoUnidadeRecolhedora>74101</codigoUnidadeRecolhedora>
                  <subNatureza>160</subNatureza>
               </detalheCaptacaoBaseExterna>
               <detalheCaptacaoBaseExterna>
                  <codigoNaturezaReceita>19210600</codigoNaturezaReceita>
                  <codigoUnidadeRecolhedora>74101</codigoUnidadeRecolhedora>
                  <subNatureza>160</subNatureza>
               </detalheCaptacaoBaseExterna>
               <detalheCaptacaoBaseExterna>
                  <codigoNaturezaReceita>16000201</codigoNaturezaReceita>
                  <codigoUnidadeRecolhedora>25101</codigoUnidadeRecolhedora>
                  <subNatureza>160</subNatureza>
               </detalheCaptacaoBaseExterna>
               <detalheCaptacaoBaseExterna>
                  <codigoNaturezaReceita>19159901</codigoNaturezaReceita>
                  <codigoUnidadeRecolhedora>74101</codigoUnidadeRecolhedora>
                  <subNatureza>160</subNatureza>
               </detalheCaptacaoBaseExterna>
            </detalhesCaptacaoBaseExterna>
         </return>
      </ns2:consultarDetalhesPorGrupoResponse>
   </env:Body>
  </env:Envelope>

==== 2.3 Consultar Disponibilidade de Captação de Base Externa ====


**Nome da operação na interface do serviço:**
consultarDisponibilidadeCaptacaoBaseExterna

**Parâmetro(s) de entrada:**
|Parâmetro|Tipo(tamanho)|Observações|
|credencial|CredencialDTO|Credencial do usuário|

**Tipo de Retorno:**
RetornoCaptacaoBaseExternaDTO


**Exemplo:**

Requisição:

  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://servicoweb.siop.sof.planejamento.gov.br/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:consultarDisponibilidadeCaptacaoBaseExterna>
         <credencial>
            <perfil>32</perfil>
            <senha>***</senha>
            <usuario>WS-SISTEMA</usuario>
         </credencial>
      </ser:consultarDisponibilidadeCaptacaoBaseExterna>
   </soapenv:Body>
  </soapenv:Envelope>

Resposta:

  <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sof="http://servicoweb.siop.sof.planejamento.gov.br/">
   <env:Header>
      <sof:request>948F90F1FA0BDB402709427F0BE5886C</sof:request>
   </env:Header>
   <env:Body>
      <ns2:consultarDisponibilidadeCaptacaoBaseExternaResponse xmlns:ns2="http://servicoweb.siop.sof.planejamento.gov.br/">
         <return>
            <sucesso>true</sucesso>
            <captacoesBaseExterna>
               <captacaoBaseExterna>
                  <codigoCaptacaoBaseExterna>466</codigoCaptacaoBaseExterna>
		  <descricao>Descricao da Captacao Disponivel</descricao>
                  <disponibilidades>
                     <disponibilidade>
                        <grupoNaturezaReceita>90000</grupoNaturezaReceita>
                        <exercicio>2014</exercicio>
                        <abertoParaCaptacacao>true</abertoParaCaptacacao>
                        <inicioDisponibilidade>2014-05-01T00:00:00-03:00</inicioDisponibilidade>
                        <fimDisponibilidade>2014-12-31T00:00:00-02:00</fimDisponibilidade>
                     </disponibilidade>
                     <disponibilidade>
                        <grupoNaturezaReceita>90000</grupoNaturezaReceita>
                        <exercicio>2015</exercicio>
                        <abertoParaCaptacacao>false</abertoParaCaptacacao>
                     </disponibilidade>
                     <disponibilidade>
                        <grupoNaturezaReceita>90000</grupoNaturezaReceita>
                        <exercicio>2016</exercicio>
                        <abertoParaCaptacacao>false</abertoParaCaptacacao>
                     </disponibilidade>
                     <disponibilidade>
                        <grupoNaturezaReceita>90000</grupoNaturezaReceita>
                        <exercicio>2017</exercicio>
                        <abertoParaCaptacacao>false</abertoParaCaptacacao>
                     </disponibilidade>
                     <disponibilidade>
                        <grupoNaturezaReceita>20000</grupoNaturezaReceita>
                        <exercicio>2014</exercicio>
                        <abertoParaCaptacacao>true</abertoParaCaptacacao>
                        <inicioDisponibilidade>2014-05-01T00:00:00-03:00</inicioDisponibilidade>
                        <fimDisponibilidade>2014-12-31T00:00:00-02:00</fimDisponibilidade>
                     </disponibilidade>
                     <disponibilidade>
                        <grupoNaturezaReceita>20000</grupoNaturezaReceita>
                        <exercicio>2015</exercicio>
                        <abertoParaCaptacacao>false</abertoParaCaptacacao>
                     </disponibilidade>
                     <disponibilidade>
                        <grupoNaturezaReceita>20000</grupoNaturezaReceita>
                        <exercicio>2016</exercicio>
                        <abertoParaCaptacacao>false</abertoParaCaptacacao>
                     </disponibilidade>
                     <disponibilidade>
                        <grupoNaturezaReceita>20000</grupoNaturezaReceita>
                        <exercicio>2017</exercicio>
                        <abertoParaCaptacacao>false</abertoParaCaptacacao>
                     </disponibilidade>
                     
                  </disponibilidades>
               </captacaoBaseExterna>
            </captacoesBaseExterna>
         </return>
      </ns2:consultarDisponibilidadeCaptacaoBaseExternaResponse>
   </env:Body>
  </env:Envelope>


===== Estruturas de Entrada/Saída e Retorno =====

As informações que trafegam pelo serviço são organizadas em estruturas de dados que atuam como entrada (parâmetros) e retorno das operações. Enquanto os dados são manipulados pelos sistemas,  seja nos clientes ou no servidor, essas informações ficam alocadas em entidades que, no contexto de web services, podem ser chamadas de Objetos de Transferência de Dados, ou DTOs (sigla de Data Transfer Objects). Um DTO é uma classe de objetos que descreve os atributos (e as operações de atribuição e consulta de seus valores) de determinado conceito envolvido no domínio de um problema. No momento da comunicação, seja na requisição ou na resposta, os DTOs são transformados em estruturas XML formatadas de acordo com a especificação contida no documento descritor do web service (WSDL).

As linguagens de programação modernas possuem ferramentas que automatizam o processo de construção dos DTOs a partir do WSDL, bem como bibliotecas com funcionalidades que tornam transparente para o desenvolvedor o processo de tradução de DTO para XML e vice-versa.

**Entradas**

==== CaptacaoBaseExternaDTO ====

|Atributo|Tipo|Observações|
|codigoCaptacaoBaseExterna|Integer|Código da captação base externa. Ver operação Consultar Disponibilidade de Captação de Base Externa.|
|descricao|String| |
|detalhesBaseExterna|List<CaptacaoDetalheBaseExternaDTO>| |
|disponibilidades|List<DisponibilidadeCaptacaoBaseExternaDTO>|Não preencher. Usado apenas como retorno de algumas operações.|

==== CredencialDTO ====

Esta estrutura é composta pelas informações necessárias para que a aplicação cliente se identifique junto ao serviço. A credencial a ser utilizada nos web services do SIOP é específica para esse fim e não é válida para acessar a aplicação web.

|Atributo|Tipo(tamanho)|Observações|
|usuario|Texto|Login do usuário no SIOP|
|senha|Texto|Hash MD5 da senha do usuário no SIOP|
|perfil|Inteiro|Perfil com o qual o usuário deseja realizar determinada operação.|

==== CaptacaoDetalheBaseExternaDTO ====


|Atributo|Tipo(tamanho)|Observações|
|codigoNaturezaReceita|String(8)| |
|codigoUnidadeRecolhedora|String(5)| |
|subNatureza|String(3)| |
|justificativa|String(min=1, max=2000)| |
|metodologia|String(min=1, max=2000)| |
|memoriaDeCalculo|String(min=1, max=2000)| |
|valoresBaseExterna|List<CaptacaoValorBaseExternaDTO>| |
|versao|Integer|Não preencher. Usado apenas como retorno de algumas operções.|
|usuarioInclusao|String(min 3)|Não preencher. Usado apenas como retorno de algumas operções.|
|usuarioAlteracao|String(5)|Não preencher. Usado apenas como retorno de algumas operções.|

==== CaptacaoValorBaseExternaDTO ====

|Atributo|Tipo(tamanho)|Observações|
|exercicio|Integer| |
|valor|Numeric(16,2)| |
|usuarioInclusao|String|Não preencher. Usado apenas como retorno de algumas operções.|
|usuarioAlteracao|String|Não preencher. Usado apenas como retorno de algumas operções.|

==== DisponibilidadeCaptacaoBaseExternaDTO ====

|Atributo|Tipo(tamanho)|Observações|
|grupoNaturezaReceita|String(5)| |
|exercicio|Integer| |
|abertoParaCaptacacao|boolean| |
|inicioDisponibilidade|Date| |
|fimDisponibilidade|Date| |


**Retornos**

==== RetornoCaptacaoBaseExternaDTO ====

|Atributo|Tipo(tamanho)|Observações|
|captacoesBaseExterna|List<CaptacaoBaseExternaDTO>| |
|sucesso|boolean|Indica se a requisição foi processada com sucesso.|
|mensagensErro|List<String>|Contém a lista de mensagens de erro nos casos em que sucesso retornar valor igual false.|


==== RetornoCaptacaoDetalheBaseExternaDTO ====

|Atributo|Tipo(tamanho)|Observações|
|detalhesCaptacaoBaseExterna|List<CaptacaoDetalheBaseExternaDTO>| |
|sucesso|boolean|Indica se a requisição foi processada com sucesso.|
|mensagensErro|List<String>|Contém a lista de mensagens de erro nos casos em que sucesso retornar valor igual false.|