SIDXML

SIDXML é o conceito atribuído à forma de agrupar ações SID em texto pseudo XML e submetê-las em uma única requisição HTTP. O benefício é a possibilidade de processamento agrupado dentro de uma transação de banco, assim ocorrendo alguma falha todo o bloco de comandos SID é desfeito, além de reduzir o tráfego via rede. Outra característica é a possibilidade de utilizar o "retorno" de ações como parâmetros em outras.

Sintaxe

Para utilizá-lo, deve-se enviar a ação de "login" (EXESENHA) normalmente e, em seguida, enviar a ação "SID.SRV.XML" com o texto XML. O texto XML deve ser montado como abaixo:

<sidxml>
	<sid acao='[ACAOSID]' retorno='[RETORNO]'>
		<param nome='[PARAMETRO]' valor='[VALOR]' />
		...demais parâmetros...
	</sid>
	...demais ações...
</sidxml>				

Onde:

* Parâmetro opcional

Observações técnicas

• Para submeter o texto XML, deve-se utilizar sempre o método "POST";
• Não há limite de quantidade de ações ou parâmetros, apenas o tamanho final do texto XML (1 Mb);
• Para utilizar o conteúdo de uma variável interna, deve-se preceder o nome da variável um "@" no parâmetro valor. Exemplo: <param nome='NUMPED' valor='@RETORNO_PEDIDO'>;
• Os valores dos parâmetros devem sempre estar delimitados por apóstrofos ('), independente do tipo de conteúdo;
• O Sapiens Server considera falha ou erro, todo retorno de ação iniciando com "ERRO:";

Parâmetros do SIDXML

A passagem de parâmetros para o SIDXML pode ser feita definindo o primeiro sub-elemento do SIDXML com o rótulo "param", sendo os atributos deste elemento considerados como parâmetros.

Os parâmetros existentes, e seus possíveis valores, são:

1. retorno – indica o formato de resultado da execução da ação SIDXML. Possíveis valores:
   1. <padrão> – o resultado da ação é um texto simples "OK" ou "ERRO:....";
   2. XML – o resultado da ação é um XML indicando o retorno individual de cada ação;
2. transacao – indica o modo de tratamento de transações de banco de dados. Possíveis valores:
   1. <padrão> – todo conteúdo do SIDXML é processado dentro de uma transação única, assim ocorrendo erro em alguma ação, tudo é desfeito;
   2. INDIVIDUAL – cada ação dentro do SIDXML é processado em sua própria transação, assim ocorrendo erro em alguma ação, somente o resultado desta ação é desfeito, sendo as ações posteriores também processadas;

Exemplo:

<sidxml>
	<param retorno='XML' transacao='INDIVIDUAL' />
	...ações...
</sidxml>

A utilização de parâmetro transacao como INDIVIDUAL torna obrigatório a utilização do parâmetro retorno como XML.

Limitações

• Por questões técnicas internas, o XML não deverá conter quebras de linha, ou seja, todo o conteúdo deverá ser submetido numa única linha, exemplo: <sidxml><sid acao=...><...><...></sidxml>
• Não utilizar o cabeçalho padrão do XML (<?xml version="1.0"?>);
• Não utilizar caracteres como "?" e "&" no XML;
• Não utilizar o caractere apóstrofo (') no valor de um parâmetro;
• A ação SID.SRV.EXEREL não pode ser utilizada no SIDXML;

Exemplo

O exemplo de XML a seguir, realiza as seguintes funções:

• Cadastra um novo cliente e suas definições;
• Gera uma nota fiscal de venda e seus itens (para este novo cliente);
• Processa o fechamento da nota fiscal;
• Executa uma regra LSP para buscar uma informação adicional da base;
• Gera o boleto cliente do cliente e o envia via e-mail;

<sidxml>
	<param retorno='XML' />
	<sid acao='SID.CLI.GRAVAR' retorno='RET_CODCLI'>
		<param nome='NOMCLI' valor='Senior Sistemas' />
		<param nome='APECLI' valor='Senior' />
		<param nome='TIPCLI' valor='J' />
		<param nome='CGCCPF' valor='80680093000181' />
		<param nome='ENDCLI' valor='R. Luiz Sachtleben, 115 Victor Konder' />
		<param nome='SIGUFS' valor='SC' />
		<param nome='CEPCLI' valor='89012530' />
		<param nome='EMACLI' valor='senior@senior.com.br' />
	</sid>
	<sid acao='SID.CLI.GRAVARDEFINICOES'>
		<param nome='CODCLI' valor='@RET_CODCLI' />
		<param nome='CODREP' valor='1' />
		<param nome='VLRLIM' valor='1000000' />
		<param nome='LIMAPR' valor='S' />
	</sid>
	<sid acao='SID.NFV.GRAVAR' retorno='RET_NUMNFV'>
		<param nome='CODSNF' valor='U' />
		<param nome='CODCLI' valor='@RET_CODCLI' />
		<param nome='TNSPRO' valor='512' />
	</sid>
	<sid acao='SID.NFV.GRAVARPRODUTOS'>
		<param nome='CODSNF' valor='U' />
		<param nome='NUMNFV' valor='@RET_NUMNFV' />
		<param nome='SEQIPV' valor='1' />
		<param nome='CODPRO' valor='CA000101' />
		<param nome='CODDER' valor='M' />
		<param nome='QTDFAT' valor='1' />
		<param nome='PREUNI' valor='19.50' />
	</sid>
	<sid acao='SID.NFV.FECHAR'>
		<param nome='CODSNF' valor='U' />
		<param nome='NUMNFV' valor='@RET_NUMNFV' />
	</sid>
	<sid acao='SID.SRV.REGRA' retorno='RET_TITULO_GERADO'>
		<param nome='NUMREG' valor='123' />
		<param nome='vAlfaNumNfv' valor='@RET_NUMNFV' />
		<param nome='vAlfaCodSnf' valor='U' />
	</sid>
	<sid acao='SID.SRV.EXEBLO' retorno='RET_ARQUIVO'>
		<param nome='NOME' valor='CN00999.BLO' />
		<param nome='NUMTIT' valor='@RET_TITULO_GERADO' />
		<param nome='CODTPT' valor='01' />
		<param nome='FORMATO' valor='JPEG' />
		<param nome='QUALIDADE' valor='80' />
	</sid>
	<sid acao='SID.SRV.EMAIL'>
		<param nome='DESTINATARIO' valor='senior@senior.com.br' />
		<param nome='ASSUNTO' valor='Seu boleto para pagamento segue em anexo' />
		<param nome='ANEXO' valor='@RET_ARQUIVO' />
	</sid>
</sidxml>

Abaixo um exemplo demonstrando como montar um XML dentro de regras LSP:

Definir Alfa XML;
Definir Alfa URL;
Definir Alfa RETORNO;
...
XML = "<sidxml>";
XML = XML + "<sid acao='SID.SRV.ALTEMPFIL'>";
XML = XML + "<param nome='CODEMP' valor='2'/>";
XML = XML + "<param nome='CODFIL' valor='3'/>";
XML = XML + "</sid>";
XML = XML + "</sidxml>";
...
URL= "http://.../sapiensweb/conector?SIS=CO&LOGIN=SID&ACAO=SID.SRV.XML&USER=...";
SapiensSIDEx(URL, XML, "", "", "", RETORNO);