Web Service para desenvolvimento/testes

Por segurança o WSE só permite conexões HTTPS. Os serviços são compostos de um ou várias operações. As operações implementadas seguem uma mesma regra de formação. Todos tem um cabeçalho (header) de segurança (autenticação) e retorno dos métodos sempre será um “responseTCEWS”. No header será passado o usuário (wsse:Username) e a senha (wsse:Password). Este usuário e senha será criado no sistema e-Sfinge Web, como qualquer outro usuário, mas deve possuir o perfil: “WS e-Sfinge”. Um usuário poderá possuir outros perfis, mas somente será considerado no WSE o perfil: “WS e-Sfinge”. Segue um exemplo do header:

<soapenv:Header>
 <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-
wss-wssecurity-utility-1.0.xsd">
 <wsse:UsernameToken>
 <wsse:Username>USUARIO</wsse:Username>
 <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-tokenprofile-1.0#PasswordText">SENHA</wsse:Password>
 </wsse:UsernameToken>
 </wsse:Security>

O Response TCEWS, resposta das operações, é composto de três campos: status, mensagem e dados. O status, retorna uma situação (ERRO ou OK). O OK significa que o serviço foi executado com
sucesso. O ERRO significa que a operação não pode ser executada com sucesso. A mensagem é um descritivo do resultado da operação, sendo com status ERRO ou OK.

O dados pode variar conforme o serviço e sua operação. Este é o retorno efetivo das informações solicitadas. Este campo é um mapa composto por uma chave (key) e elemento de resposta (value). O
elemento de resposta pode ser um elemento simples ou complexo. Simples são elementos como inteiro, data ou sequência de caracteres. Complexo pode ser um vetor de elementos ou um outro mapa. O tipo de cada elemento de resposta é definido no “xsi:type”.

Um caso particular, é são os serviço do tipo “enviar“. O sistema retornará status OK se conseguir receber os dados e processá-los, mesmo que o resultado dos elementos a serem inseridos retorne erro. Neste caso o erro individual dos registros retornará no campo dados.

Exemplo de resposta da operação obterNovoToken com erro:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Body>
 <ns2:obterTokenResponse xmlns:ns2="http://token.ws.tce.sc.gov.br/">
 <return>
 <dados></dados>
 <mensagem>Dados não compactados. Deve-se usar compactação (gzip) ao usar o
WebService. Header enviado:...</mensagem>
 <status>ERRO</status>
 </return>
 </ns2:obterTokenResponse>
 </soap:Body>
</soap:Envelope>

O WSE exige o envio de dados com compressão, GZIP. Isso permitirá maior agilidade no envio de informações além de grande economia de rede. O envio de dados compactados é obrigatório desde 28/08/2015. Caso qualquer chamada do WSE não use compactação, retornará o erro demostrado a seguir:

 <soap:Body>
 <ns2:obterTokenResponse xmlns:ns2="http://token.ws.tce.sc.gov.br/">
 <return>
 <dados></dados>
 <mensagem>Dados não compactados. Deve-se usar compactação (gzip) ao usar o
WebService. Header enviado:...</mensagem>
 <status>ERRO</status>
 </return>
 </ns2:obterTokenResponse>
 </soap:Body>
</soap:Envelope>

Recomendamos que todas as chamadas sejam enviadas com os parâmetros: “Content-Length” (tamanho do “pacote”) e “user-agent” (definição da plataforma usada no envio do WS) no cabeçalho HTTP.
Para todas as operações do WSE todos os campos (parâmetros) são obrigatórios, salvo quando a definição da operação ou do assunto permita que este seja opcional. Para atributos opcionais ou
condicionais (obrigatório dependendo do contexto), não devem ser enviados com valor nulo, e sim não criem a TAG no XML. Seguem exemplo da forma correta e errada de serem enviados atributos opcionais/ condicionais sem valor:

Forma CORRETA de envio de um atributo opcional com valor:
<assunto><attr>XX</attr><attrOpcional>XX</attrOpcional></assunto>
Forma CORRETA de envio de um atributo opcional sem valor:
<assunto><attr></attr></assunto>
Formas ERRADAS de envio de um atributo opcional sem valor:
<assunto><attr>XX</attr><attrOpcional></attrOpcional></assunto>
Ou
<assunto><attr>XX</attr><attrOpcional/></assunto>

Cada solicitação enviada via Web Service ao TCE deve-se preencher os elementos com as seguintes regras:

Valores Financeiros – deverão ser preenchidos com caracteres ISO-8859-1 numéricos e ponto para posição decimal. Ex.: Para informar R$ 1.510,15 deve ser preenchido como 1510.15
Valores Percentuais – deverão ser preenchidos com caracteres ISO-8859-1 numéricos e ponto para posição decimal. Ex.: Para informar 15% deve ser preenchido como 15.00
Quantidades – deverão ser preenchidas com caracteres ISO-8859-1 numéricos e ponto para posição de milésimos. Ex.: Para informar 184,3251 deve ser preenchido como 184.3251
Valores Inteiros – deverão ser preenchidos com caracteres ISO-8859-1 numéricos. Não admite ponto decimal. Ex.: Para informar 120 deve ser preenchido como 120
Valores Lógicos – são campos com uma posição e representam indicação de conformidade ou negação. Tais campos assumem somente os valores “S” ou “N” (Sim ou Não) usando a codificação ISO-8859-1.
Dados carácter – deverão ser preenchidos com caracteres ISO-8859-1 letras, números e símbolos.

Para executar algumas operações haverá a necessidade de entrar em uma fila virtual de acesso. Esta fila foi criada para evitar que determinado usuário use os recursos do TCE impedindo que outros usuários o façam. O usuário (sistema que usa o Web Service) receberá um token (uma string com 36 caracteres aleatórios) e se for necessário de tempos em tempos verificará se chegou a sua vez. O token também representará uma sessão de trabalho ou de envio de dados ao TCE. Esta sessão possui um tempo de expiração (time out) de 360 segundos. Cada nova chamada do Web Service reiniciará o contador de time out. Caso ocorra um time out de token e se este teve elementos inseridos associados a ele, estes elementos serão removidos, se for o caso. Isso equivalerá a chamada da operação cancelarTransferencia (descrita na sequência deste documento), no caso dos serviços de envio de informações ao TCE. Um token após usado que ocorreu um time out não poderá ser reaproveitado e deverá ser descartado, independente da sua situação final. É permite somente um token ativo por unidade gestora. Só será permitido a solicitação de um novo token se o anterior estiver com uma situação “inativo”. Cada novo envio/consulta deve-se solicitar um novo token.

Os serviços que usam a fila virtual estão divididos em dois grupos. O primeiro grupo, serviços enviar assuntos, necessitam de uma confirmação após o envio. Ou seja, deve-se executar a operação cancelarTransferencia ou finalizarTransferencia após a transferência dos dados. A seguir as situações (status) que um token pode estar, para os serviços enviar assuntos.

 Imagem 1 - Situações possíveis do token, serviços enviar assuntos

O Segundo grupo são as operações operação listar de cada serviço (assunto), Consultar operação listar e para o serviço ArquivoFisico operação enviarArquivo. Para estas operações, depois do envio ou consulta finalizada não deve-se executar o iniciarTransferencia, cancelarTransferencia ou finalizarTransferencia. O token será finalizado após o envio da consulta ser respondida a unidade, ou seja sua situação será modificada automaticamente para a situação inativo – “Finalizado”. A seguir as situações (status) que um token pode estar, para os serviços: Consultar operação listar e para o ArquivoFisico operação enviarArquivo.

Para os dois grupos, se um token não chegou em seu status final poderá ser cancelado usando a operação cancelarTransferencia ou esperar que ocorra o timeout. Um caso típico para isso é quando uma token é obtido com sucesso mas ao longo de seu ciclo de vida ocorre algum problema na execução das demais operações. Neste caso o token não será automaticamente removido depois da operação que resultou em erro. O desenvolvedor deverá utilizar a operação “cancelarTransferencia” ou esperar o timeout do token. Esta regra vale para os dois grupos de assuntos. Considera-se uma
execução com erro se o campo “status” retornar “ERRO” ou não retornar este campo (por exemplo quando ocorra um problema de formatação do XML).
Ou seja, o sistema somente avançará ou permitirá avançar para a próxima situação se a tag “status” retornar “OK”. Segue um exemplo de retorno de status ERRO e um com erro na formatação do XML, dois casos que o token não será cancelado.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Body>
 <ns2:enviarArquivoResponse xmlns:ns2="http://arquivofisico.ws.tce.sc.gov.br/">
 <return>
 <dados/>
 <mensagem>O conteúdo do arquivo a.pdf não corresponde a extensão, favor conferir se o arquivo foi gerado
corretamente.</mensagem>
*** <status>ERRO</status> ***
 </return>
 </ns2:enviarArquivoResponse>
 </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Body>
 <soap:Fault>
 <faultcode>soap:Client</faultcode>
 <faultstring>Problems creating SAAJ object model</faultstring>
 </soap:Fault>
 </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:enviarArquivoResponse xmlns:ns2="http://arquivofisico.ws.tce.sc.gov.br/">
<return>
<dados>...<dados/>
<mensagem>Arquivo salvo com sucesso</mensagem>
***<status>OK</status>***
</return>
</ns2:enviarArquivoResponse>
</soap:Body>
</soap:Envelope>

Retorna um token para a unidade gestora poder usar o serviço do TCE. Permite somente um token por unidade gestora.

Definição:          

• obterToken(inteiro codigoUnidadeGestora)

Parâmetros:

• codigoUnidadeGestora: código da Unidade Gestora conforme serviço listar da tabela unidades gestoras.

Resposta (campos dados):

• posicao: posição atual do seu token na fila
• situacao: situação do token
• chaveToken: o token em si, deverá ser usado nos demais serviços

Exemplo:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tok="http://token.ws.tce.sc.gov.br/">
 <soapenv:Header>
 <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
 <wsse:UsernameToken>
 <wsse:Username>USUARIO</wsse:Username>
 <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">SENHA</wsse:Password>
</wsse:UsernameToken>
 </wsse:Security>
 </soapenv:Header>
 <soapenv:Body>
 <tok:obterToken>
 <codigoUg>10006</codigoUg>
 </tok:obterToken>
 </soapenv:Body>
</soapenv:Envelope>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Body>
 <ns2:obterTokenResponse xmlns:ns2="http://token.ws.tce.sc.gov.br/">
 <return>
 <dados>
 <entry>
 <key>chaveToken</key>
<value xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance">d95a313b-4ba9-49b1-aca0-53c1f1bd16a4</value>
 </entry>
 <entry>
 <key>posicao</key>
<value xsi:type="xs:int" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">2</value>
 </entry>
 <entry>
 <key>situacao</key>
<value xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">Pronto
para envio ou consulta</value>
 </entry>
 </dados>
 <mensagem>Token criado com sucesso</mensagem>
 <status>OK</status>
 </return>
 </ns2:obterTokenResponse>
 </soap:Body>
</soap:Envelope>