Sobre o Web Service

Aprenda a sincronizar vendas, movimentações de valores nos caixas e transações TEFs de uma de Ponto de Venda à uma Retaguarda da Saurus.

Visão geral

O Web Service Recepção é um dos três serviços desenvolvidos pelo time da Saurus que propicia a sincronização de vendas da Retaguarda com o PDV. A principal funcionalidade, envArqIntegracao, oferece o envio e alteração de vendas, bem como lançar movimentações de valores no caixa e transações TEFs. Ao longo da documentação, você poderá aprender tudo sobre as ações deste serviço.

http://wsrecepcao.saurus.net.br/v001/serviceRecepcao.asmx

Glossário

Entenda os principais termos aplicados nas páginas da documentação:

Termo	Descrição
Adquirente	Empresa administradora das transações financeiras.
Arquivo de Envio	Arquivo XML compactado submetido na requisição.
Arquivo de Retorno	Arquivo XML compactado retornado na resposta.
Campo	Utilizado como sinônimo para elemento de arquivos XML.
CCe	Carta de Correção Eletrônica.
Método	Endpoint do Web Service.
PDV	Ponto de Venda.
Retaguarda	Sistema de gestão responsável pela manutenção dos cadastros. Exemplo: Saurus V4 - saiba mais.
Sangria	Transferência de valores que estão em excesso no caixa.
Suprimento	Adição de dinheiro ao caixa.
TEF	Transferência eletrônica de fundos.

SOAP e WSDL

A comunicação com o Service Envios é realizada através do protocolo SOAP, especificado pela W3C - World Wide Web Consortium. As requisições podem ser feitas com as versões 1.1 e 1.2 do Simple Object Access Protocol, que são detalhadas oficialmente aqui.

Confira um exemplo:

POST /v001/serviceRecepcao.asmx HTTP/1.1
Host: wsenvios.saurus.net.br
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://saurus.net.br/envArqIntegracao"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <envArqIntegracao xmlns="http://saurus.net.br/">
      <xBytesParametros>base64Binary</xBytesParametros>
      <xSenha>string</xSenha>
    </envArqIntegracao>
  </soap:Body>
</soap:Envelope>

As funcionalidades do Web Service são descritas com o WSDL - Web Service Description Language, que basicamente é um contrato entre o cliente e o servidor. Os métodos, parâmetros de entrada e saída são definidos com essa linguagem. Para mais informações, consulte a documentação do SoapUI.

O detalhamento do serviço pode ser acessado pela seguinte URL:

http://wsrecepcao.saurus.net.br/v001/serviceRecepcao.asmx

Arquivos de Envio e Retorno

A comunicação com a Retaguarda é estabelecida a partir dos métodos disponíveis no Web Service - todos eles trabalham com o recebimento de arquivos XML. Para o envio desses arquivos na requisição, eles devem ser compactados em GZip, de modo que os dados informados sejam processados e posteriormente devolvidos na resposta com o mesmo formato.

Por exemplo, considere o XML abaixo:

<xmlIntegracao>
    <Dominio>dev08</Dominio>
    <IdLoja>1</IdLoja>
    <IdCaixa>1</IdCaixa>
    <NumCaixa>1</NumCaixa>
    <IdReg>8bf18368-efce-4ac8-b930-b609f8f61af9</IdReg>
    <ChaveTerminal>38e358ee-3553-4622-81f8-fd9c323f45b4</ChaveTerminal>
    <TpLanc>0</TpLanc>
    <TpArqXml>20</TpArqXml>
</xmlIntegracao>

O procedimento a seguir deve ser feito com o arquivo antes de seu envio, utilizando a linguagem de programação C#:

XElement xArquivo = new XElement("xmlIntegracao");
xArquivo.Add(new XElement("Dominio", xDominio));
xArquivo.Add(new XElement("IdLoja", xIdLoja));
xArquivo.Add(new XElement("IdCaixa", xIdCaixa));
xArquivo.Add(new XElement("NumCaixa", xNumCaixa));
xArquivo.Add(new XElement("IdReg", xIdReg));
xArquivo.Add(new XElement("ChaveTerminal", xChaveTerminal));
xArquivo.Add(new XElement("TpLanc", xTpLanc));
xArquivo.Add(new XElement("TpArqXml", xTpArqXml));
byte[] xArquivoEnvio = Zip.ComprimirArquivo(Encoding.UTF8.GetBytes(xArquivo.ToString(SaveOptions.DisableFormatting)));

Fique tranquilo, pois os arquivos completos que precisam ser enviados, e os que são retornados, estão documentados nas próximas seções.

Autenticação nos métodos

Os métodos do Web Service exigem o envio de um elemento denominado xSenha, que permite a requisição SOAP ser feita com sucesso. Para obter essa senha criptografada, você deve primeiramente nos contatar.

Caso esteja interessado, clique aqui e envie sua mensagem.

Respostas padronizadas

Os métodos do Service Envios devolvem elementos padronizados em suas respostas:

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <envArqIntegracaoResponse xmlns="http://saurus.net.br/">
      <envArqIntegracaoResult>base64Binary</envArqIntegracaoResult>
      <xRetNumero>int</xRetNumero>
      <xRetTexto>string</xRetTexto>
    </envArqIntegracaoResponse>
  </soap:Body>
</soap:Envelope>

No caso, o método envArqIntegracao foi usado de exemplo, logo os elementos Response e Result carregam o seu nome. Em contrapartida, xRetNumero e xRetTexto estão igualmente identificados em todas as respostas.

Elemento	Descrição
[nome do método]Response	Elemento raiz dentro do corpo da mensagem.
[nome do método]Result	Arquivo XML retornado do método.
xRetNumero	Retorna 0 em sucesso, e 1 em erro.
xRetTexto	Descrição da resposta do método.