Content Comparison

...

Expand

title	Serviço da fila virtual de acesso

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.

Expand

title	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.

Expand

title	Imagem 2 – Situações possíveis do token, operação enviar arquivo físico ou listar

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.

Code Block

language	xml
title	Exemplo de retorno de status ERRO, com o status entre ***.

<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>

Code Block

language	xml
title	Exemplo de retorno de erro na formatação do XML, sem o campo de retorno status:

<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>

Code Block

language	xml
title	Exemplo de retorno de status OK, com o status entre *** (conteúdo da tag <dados> substituída por ‘...’ para simplificar exemplo):

<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>

Expand

title	Operação: obterToken

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, string descricaoEmpresaTI, string descritivoSoftware)

Parâmetros:

codigoUnidadeGestora: código da Unidade Gestora conforme serviço listar da tabela unidades gestoras.
descricaoEmpresaTI: nome da Empresa de TI responsável pela integração*
descritivoSoftware: nome do Software utilizado para integração*

Info
*(Parâmetros facultativos, para o ano de 2020, e obrigatórios, para o ano de 2021 - Utilizar String com limite máximo de 100 caracteres).

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:

Code Block

language	xml
title	Solicitação (O cabeçalho “soapenv:Header” foi omitido para simplificação da documentação):

<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>
 <descricaoEmpresaTI>Empresa</descricaoEmpresaTI>
 <descritivoSoftware>Software</descritivoSoftware>
 </tok:obterToken>
 </soapenv:Body>
</soapenv:Envelope>

Code Block

language	xml
title	Resposta:

<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>

Expand

title	Operação: obterSituacaoToken

Retorna a situação do token passado como parâmetro. Para evitar solicitações indefinidas a este serviço o sistema punirá com a remoção do token da fila sempre que for feita duas chamadas seguidas do serviço obterSituacaoToken em menos de cinco segundos.

Definição:

obterSituacaoToken(caracteres token)

Parâmetros:

token: o token recebido no serviço obterToken.

Resposta (campos dados):

posicao: posição atual do seu token na fila
situacao: situação do token

Exemplo

Code Block

language	xml
title	Solicitação (O cabeçalho “soapenv:Header” foi omitido para simplificação da documentação):

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tok="http://token.ws.tce.sc.gov.br/">
 <soapenv:Header…
 <soapenv:Body>
 <tok:obterSituacaoToken>
 <token>d95a313b-4ba9-49b1-aca0-53c1f1bd16a4</token>
 </tok:obterSituacaoToken>
 </soapenv:Body>
</soapenv:Envelope>

Code Block

language	xml
title	Resposta:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Body>
 <ns2:obterSituacaoTokenResponse xmlns:ns2="http://token.ws.tce.sc.gov.br/">
 <return>
 <dados>
 <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">1</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>Situação token obtida com sucesso</mensagem>
 <status>OK</status>
 </return>
 </ns2:obterSituacaoTokenResponse>
 </soap:Body>
</soap:Envelope>

Expand

title	Operação: iniciarTransferencia

Antes de iniciar a transferência dos dados propriamente dita será necessário executar o serviço iniciarTransferencia.

Definição:

iniciarTransferencia (caracteres token)

Parâmetros:

token: o token recebido no serviço obterToken.

Resposta (campos dados): vazio, não retorna valores.

Exemplo:

Code Block

language	xml
title	Solicitação (O cabeçalho “soapenv:Header” foi omitido para simplificação da documentação):

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tok="http://token.ws.tce.sc.gov.br/">
 <soapenv:Header...
 <soapenv:Body>
 <tok:iniciarTransferencia>
 <token>d95a313b-4ba9-49b1-aca0-53c1f1bd16a4</token>
 </tok:iniciarTransferencia>
 </soapenv:Body>
</soapenv:Envelope>

Code Block

language	xml
title	Resposta:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Body>
 <ns2:iniciarTransferenciaResponse xmlns:ns2="http://token.ws.tce.sc.gov.br/">
 <return>
 <dados/>
 <mensagem>Início de transferência liberado</mensagem>
 <status>OK</status>
 </return>
 </ns2:iniciarTransferenciaResponse>
 </soap:Body>
</soap:Envelope>

Expand

title	Operação: cancelarTransferencia

Ao final da transferência caso queria remover todos os elementos inseridos nesta sessão, ou seja todos os elementos ligados a determinado token passado para o serviço. Uma vez executado este serviço o token atual será descartado.

Definição:

cancelarTransferencia (caracteres token)

Parâmetros:

token: o token recebido no serviço obterToken.

Resposta (campos dados): vazio, não retorna valores.

Exemplo:

Code Block

language	xml
title	Solicitação (O cabeçalho “soapenv:Header” foi omitido para simplificação da documentação):

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tok="http://token.ws.tce.sc.gov.br/">
 <soapenv:Header...
 <soapenv:Body>
 <tok:cancelarTransferencia>
 <token>d95a313b-4ba9-49b1-aca0-53c1f1bd16a4</token>
 </tok:cancelarTransferencia>
 </soapenv:Body>
</soapenv:Envelope>

Code Block

language	xml
title	Resposta:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Body>
 <ns2:cancelarTransferenciaResponse xmlns:ns2="http://token.ws.tce.sc.gov.br/">
 <return>
 <dados/>
 <mensagem>Cancelada com sucesso</mensagem>
 <status>OK</status>
 </return>
 </ns2:cancelarTransferenciaResponse>
 </soap:Body>
</soap:Envelope>

Expand

title	Operação: finalizarTransferencia

Ao final da transferência caso queria confirmar todos os elementos inseridos (que não retornaram erro) nesta sessão, ou seja todos os elementos ligados a determinado token passado para o serviço. Uma vez executado este serviço o token atual será descartado.

Definição:

finalizarTransferencia (caracteres token)

Parâmetros:

token: o token recebido no serviço obterToken.

Resposta (campos dados): vazio, não retorna valores.

Exemplo:

Code Block

language	xml
title	Solicitação (O cabeçalho “soapenv:Header” foi omitido para simplificação da documentação):

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tok="http://token.ws.tce.sc.gov.br/">
 <soapenv:Header...
 <soapenv:Body>
 <tok:finalizarTransferencia>
 <token>d95a313b-4ba9-49b1-aca0-53c1f1bd16a4</token>
 </tok:finalizarTransferencia>
 </soapenv:Body>
</soapenv:Envelope>

Code Block

language	xml
title	Resposta:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Body>
 <ns2:finalizarTransferenciaResponse xmlns:ns2="http://token.ws.tce.sc.gov.br/">
 <return>
 <dados/>
 <mensagem>Finalizada com sucesso</mensagem>
 <status>OK</status>
 </return>
 </ns2:finalizarTransferenciaResponse>
 </soap:Body>
</soap:Envelope>

...

Version	Old Version 27	New Version Current
Changes made by	LUCAS GODAY	LUCAS GODAY
Saved on	Sept 23, 2020	Sept 23, 2020

Versions Compared

Key