# Sobre o Web Service

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

{% hint style="info" %}
[http://wsrecepcao.saurus.net.br/v001/serviceRecepcao.asmx](http://wsenvios.saurus.net.br/v001/serviceRecepcao.asmx)
{% endhint %}

### 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**](http://saurus.com.br/Suporte). |
| 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**](https://www.w3.org/2003/06/soap11-soap12.html).

Confira um exemplo:

```markup
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**](https://www.soapui.org/soap-and-wsdl/working-with-wsdls.html).

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

{% hint style="info" %}
[http://wsrecepcao.saurus.net.br/v001/serviceRecepcao.asmx](http://wsenvios.saurus.net.br/v001/serviceRecepcao.asmx)
{% endhint %}

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

```markup
<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#:

```csharp
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**](http://saurus.com.br/#contato) e envie sua mensagem.

### Respostas padronizadas

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

```markup
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.           |