Integração e-Commerce para Desenvolvedores : MOVERE Software

1. Introdução

Este documento tem o intuito de instruir o Desenvolvedor de como consumir o WebService de Integração com e-commerce.

1.1 Escopo

O objetivo da exportação é disponibilizar um XML contendo todos os dados dos Produtos, Grupos, Famílias, Linhas de Produtos. Este XML deverá ser consumido pelo e-commerce para sincronizar os dados com o MOVERE.

2. Estrutura do XML

O XML foi projetado para conter toda a estrutura e dados necessários para a integração. Logo, sempre será gerado apenas um XML contendo todos os dados desejados.

2.1 Visão Geral do XML

2.2 Formatação do XML

Os campos com tipos específicos devem ser formatados da seguinte maneira:

Decimais: Formatados sem separador de milhar e utilizando o ponto como separador de decimais.
Data: Deve estar no formato YYYY-MM-DD

2.3 Detalhe dos elementos Primários/Secundários do XML

KasterWeb: Elemento raiz do XML.

Itens: Elemento que contém uma lista interna com todos os itens.

Item: Elemento filho de Itens que contém todos os dados de um Item.
Código Item: Elemento filho de Item apresentando a chave primaria do item. Elemento do tipo inteiro.
Descrição Item: Elemento filho de Item apresentando a descrição Nome do item. Elemento do tipo Texto com até 50 caracteres.
Embalagem: Elemento filho de Item apresentando o tipo de embalagem que o item se encaixa ex: unidade, caixa etc. Elemento do tipo Texto com até 50 caracteres.
Preço: Elemento filho de Item apresentando o valor unitário do item. Elemento do tipo Valor com até duas casas decimais.
Estoque: Disponível Elemento filho de Item apresentando a quantidade do item disponível no estoque. Elemento do tipo Valor com até três casas decimais.
Código Grupo De Itens: Elemento filho de Item apresentando qual o grupo de itens o item pertence. Elemento do tipo Inteiro.

Grupos Itens: Elemento que contém uma lista interna com todos os Grupos de Itens.

Grupo: Elemento filho de Grupos Itens contendo todos os dados de um Grupo de Itens.
Código Grupo De Itens: Elemento filho de Grupo apresentando a chave primaria do Grupo de Itens. Elemento do tipo inteiro.
Descrição Grupo De Itens: Elemento filho de Grupo apresentando a descrição Nome do Grupo de Itens. Elemento do tipo Texto com até 50 caracteres.
Código Família De Itens: Elemento filho de Grupo apresentando qual a família de itens o grupo de itens pertence. Elemento do tipo Inteiro

Famílias Itens: Elemento que contém uma lista interna com todas as famílias de Itens.

Família: Elemento filho de Famílias Itens contendo todos os dados de uma família de Itens.
Código Família De Itens: Elemento filho de Família apresentando a chave primaria da família de Itens. Elemento do tipo inteiro.
Descrição Família De Itens: Elemento filho de Família apresentando a descrição Nome da família de Itens. Elemento do tipo Texto com até 50 caracteres.
Código Linha De Itens: Elemento filho de Família apresentando qual a linha de itens a família de itens pertence. Elemento do tipo Inteiro

Linhas Itens: Elemento que contém uma lista interna com todas as linhas de Itens.

Linha: Elemento filho de Linhas Itens contendo todos os dados de uma linha de Itens.
Código Linha De Itens: Elemento filho de Linha apresentando a chave primaria da linha de Itens. Elemento do tipo inteiro.
Descrição Linha De Itens: Elemento filho de Linha apresentando a descrição (Nome) da linha de Itens. Elemento do tipo Texto com até 50 caracteres.

3. Consumindo o WebServices

Os serviços disponibilizados pelo Web Service podem ser acessados através do endereço [www.endereço do sistema.com.br/movere/sistemas/eCommerce.asmx] ou [www.endereço do sistema.com.br/nome da empresa/sistemas/eCommerce.asmx]

Obs.: No header da requisição o "Content-Type" deve ser configurado com o valor "text/xml".

Os serviços disponibilizados pelo Web Service estão listados abaixo.

RetornaTodosOsProdutosCadastrados
RetornarTodosOsProdutosCadastradosComPaginacao
RetornaSomenteProdutosQueSofreramAlteracoes
RetornaStatusPedido
RegistraPedidoProntoParaFaturamento

Para utilização dos serviços é necessário as informações do site, CNPJ e Token de acesso, conforme exemplo abaixo.

RetornaTodosOsProdutosCadastrados

<RetornaTodosOsProdutosCadastrados>
  <informacaoDoSite>
    <Cnpj>?</Cnpj>
    <Token>?</Token>
  </informacaoDoSite>
</RetornaTodosOsProdutosCadastrados>

RetornaTodosOsProdutosCadastradosComPaginacao

<RetornaTodosOsProdutosCadastradosComPaginacao>
  <informacaoDoSite>
        <Cnpj>?</Cnpj>
        <Token>?</Token>
        <CnpjParceiro>?</CnpjParceiro>
  </informacaoDoSite>
  <indiceDaPagina>?</indiceDaPagina>
  <limiteDeProdutosPorPagina>?</limiteDeProdutosPorPagina>
</RetornaTodosOsProdutosCadastradosComPaginacao>

RetornaSomenteProdutosQueSofreramAlteracoes

<RetornaSomenteProdutosQueSofreramAlteracoes>
  <informacaoDoSite>
    <Cnpj>?</Cnpj>
    <Token>?</Token>
  </informacaoDoSite>
</RetornaSomenteProdutosQueSofreramAlteracoes>

RetornaStatusPedido

<RetornaStatusPedido>
  <informacaoDoSite>
    <Cnpj>?</Cnpj>
    <Token>?</Token>
  </informacaoDoSite>
  <informacaoPedido>
    <NumeroDoPedidoDoEcommerce>?</NumeroDoPedidoDoEcommerce>
  </informacaoPedido>
</RetornaStatusPedido>

RegistraPedidoProntoParaFaturamento

<RegistraPedidoProntoParaFaturamento>
  <informacaoDoSite>
    <Cnpj>?</Cnpj>
    <Token>?</Token>
  </informacaoDoSite>
  <dadosDoPedido>
    <NomeDoCliente>?</NomeDoCliente>
    <CpfOuCnpjDoCliente>?</CpfOuCnpjDoCliente>
    <RgDoCliente>?</RgDoCliente>
    <LogradouroDoCliente>?</LogradouroDoCliente>
    <BairroDoCliente>?</BairroDoCliente>
    <CepDoCliente>?</CepDoCliente>
    <CodigoIbgeDaCidadeDoCliente>?</CodigoIbgeDaCidadeDoCliente>
    <EmailDoCliente>?</EmailDoCliente>
    <Telefone>?</Telefone>
    <CodigoDoPedido>?</CodigoDoPedido>
    <DataDoPedido>?</DataDoPedido>
    <ValorOutrasDespesas>?</ValorOutrasDespesas>
    <ValorDoDesconto>?</ValorDoDesconto>
    <ValorTotalDoPedido>?</ValorTotalDoPedido>
    <ItensDoPedido>
      <ItemDoPedido>
        <CodigoDoProduto>?</CodigoDoProduto>
        <QuantidadeDoProduto>?</QuantidadeDoProduto>
        <PrecoDeVenda>?</PrecoDeVenda>
        <ValorDescontoDoItem>?</ValorDescontoDoItem>
        <NomeDoProduto>?</NomeDoProduto>
        <CodigoFabricacao>?</CodigoFabricacao>
      </ItemDoPedido>
    </ItensDoPedido>
    <ParcelasDoPedido>
      <ValorDaParcela>?</ValorDaParcela>
      <DataDeVencimentoDaParcela>?</DataDeVencimentoDaParcela>
      <CodigoDoPortadorDaParcela>?</CodigoDoPortadorDaParcela>
      <CodigoDaFormaDePagamento>?</CodigoDaFormaDePagamento>
      <Nsu>?</Nsu>
      <NossoNumero>?</NossoNumero>
    </ParcelasDoPedido>
  </dadosDoPedido>
</RegistraPedidoProntoParaFaturamento>

RetornarXmlDoPedido

<RetornarXmlDoPedido>
      <informacaoDoSite>
        <Cnpj></Cnpj>
        <Token></Token>
        <CnpjParceiro></CnpjParceiro>
      </informacaoDoSite>
      <numeroPedido></numeroPedido>
</RetornarXmlDoPedido>

4. Autenticação das requisições

Atualmente existem duas formas que o sistema utiliza para validar os tokens de acesso. A escolha da validação utilizada pelo sistema de autenticação pode ser configurada através da rotina [R29 - Parâmetros Por Empresa], por meio do parâmetro [P1173 - Modelo de Autenticação e-commerce], conforme imagem abaixo:

É possível observar que existem dois modelos de autenticação disponíveis: Token Calculado e Usuário/Senha.

4.1 Token calculado

O cálculo do token segue a regra abaixo.

Considere que a data atual seja 25/10/2016.
O número absoluto então seria 5.

A Constante A, será 45.
A Constante B, será @.
A Constante C, será 85.
A Constante D, será 33.
A Constante E, será o Número Absoluto.
A Constante F, será 99.

A senha conforme os cálculos do exemplo seria: ?@v(8Z

A senha deve estar totalmente em Lowercase, ou seja, tudo minúsculo. Então teríamos: ?@v(8z

e depois hash md5 e ficaria: f5133e06cc10af5bc1342a6655a37ffa

Obs. O token é gerado diariamente.

4.2 Usuário/Senha

Utilizando a autenticação por usuário e senha, é possível gerar um token válido a partir das credenciais do usuário a senha deve ser fornecida com todos os caracteres minúsculas, conforme exemplo:

base64(usuario:sha1(senha))

Dessa forma, para o usuário "testador" acompanhado com os dois pontos ":" e a senha "teste" criptografada(SHA1) como no seguinte exemplo resultando o token:

base64(testador:sha1(teste))

base64(testador:2e6f9b0d5885b6010f9167787445617f553a735f)

dGVzdGFkb3I6MmU2ZjliMGQ1ODg1YjYwMTBmOTE2Nzc4NzQ0NTYxN2Y1NTNhNzM1Zg==

Os usuários utilizados nesse modelo de autenticação devem ser cadastrados na rotina [R1 - Usuários].

5. Método [Retorna Somente Produtos Alterados] do WebService.

Este método tem por objetivo retornar somente os dados que sofreram alterações.

Caso a empresa altere qualquer tipo de informação no cadastro de:

Itens - R130.
Itens por Estabelecimento - R135.
Grupo de Itens - R132.
Família de Itens - R162.
Linha Itens - R178.

Estes dados serão considerados e retornados no XML para serem inseridos ou atualizados.

Esta regra também vale para os Preços e Quantidades em Estoque. Assim, sempre que houver alterações de preços e quantidades em estoque, o item será reenviado com as novas informações.

Obs:. Ao realizar a consulta deste web método, o sistema registra a data/hora desta consulta como o da última sincronização realizada, ou seja, na próxima consulta a ser realizada, irão retornar somente dados que foram alterados desde a data/hora da última consulta até a data atual:

Exemplo:

Se o produto "A" foi alterado pelo usuário dia 18/05/2017 as 08:30 Hrs, se realizada a consulta no dia 18/05/2017 as 09:00 o web método irá retornar o produto alterado normalmente.

Mas caso seja realizada uma nova consulta no dia 19/05/2017 as 08:00, se o produto "A" não sofreu alteração entre 18/05/2017 08:30 hrs até 19/05/2017 08:00 hrs, o web método não irá retornar o produto "A".

6. Método [Registra Pedido Pronto Para Faturamento] do WebService.

Este método tem o objetivo de gerar um orçamento em aberto no MOVERE, segue abaixo algumas observações sobre o método:

Caso o Cliente do pedido não esteja cadastrado no MOVERE, este será cadastrado automaticamente de acordo com as informações dos dados do pedido enviado via Web Service.
A Contábil do Cliente/ Fornecedor será a mesma que está configurada no [P48 - Conta Contábil Padrão para de Cadastro Cliente].
No campo [CodigoDaFormaDePagamento] deve ser informado o código de uma Condição de Pagamento válida [R129 - Condições de Pagamentos de Venda] no sistema MOVERE.
No campo [CodigoDoPortadorDaParcela] deve ser informado o código de um portador válido na rotina [R75 - Portadores] no sistema MOVERE.
Os informações do campos [Nsu], [NossoNumero] e [NomeDaCondicaoDePagamento] não devem ser informadas.

7. Método [Retorna Todos Os Produtos Cadastrado Com Paginação] do WebService.

Este método tem o objetivo retornar todos os produtos segmentado por páginas, desta forma reduzindo o volume de dados, segue abaixo algumas observações sobre o método:

Este método requer além dos parâmetros solicitados no método [RetornarTodosOsProdutosCadastrados], os parâmetros indiceDaPagina e o limiteDeProdutoPorPagina.
O parâmetro indiceDaPagina deve ser um valor inteiro maior ou igual a zero.
O parâmetro limiteDeProdutoPorPagina deve ser um valor inteiro maior que zero.

Exemplo: Suponha que um determinado cliente possua uma massa de dados com 10.000 produtos.

Caso seja informado nos parâmetros indiceDaPagina igual a 0 e o limiteDeProdutoPorPagina igual a 1500, o método irá retornar os primeiros 1500 produtos baseado no código do produto.

Caso seja informado nos parâmetros indiceDaPagina igual a 1 e o limiteDeProdutoPorPagina igual a 1500, o método irá retornar os produtos da posição 1500 até 2999 baseado no código do produto.

Caso o parâmetro [P1113 - Tipo de modelo de e-commerce] esteja marcado como [Outros] ou não configurado irá retornar novos campos contendo a tabela de preço adicional configurada.

8. Importação utilizando código de fabricação dos itens.

Existe a possibilidade do integrador utilizar o código de fabricação dos itens para geração de pedidos no sistema, e-commerce irá gerar os pedidos com base no código de fabricação, não o código do item, da rotina [R130 - Itens]:

Para que isso seja possível, deve ser configurado o parâmetro por empresa [P0871 - E-commerce utiliza integração dos itens por meio do campo [Código de Fabricação]?].

Ao configurar este parâmetro, ao enviar o pedido pelo método [Registra Pedido Pronto Para Faturamento], o campo [CodigoFabricacao] dos itens deverá ser preenchido obrigatoriamente, conforme o mesmo código existente na rotina [R130 - Itens]:

Caso este campo não seja enviado, o sistema irá lançar a seguinte exceção: Favor informar o código de fabricação de um produto válido.

Caso o campo [CodigoFabricacao] seja enviado, porém, não seja possível localizar um item com base no campo [Código de Fabricação], o sistema irá lançar a seguinte exceção: Não foi possível localizar um item com o código de fabricação [codigo-importado-enviado] para geração do pedido para faturamento!

Caso exista no MOVERE mais que um item na rotina [R130 - Itens] com o mesmo código de fabricação, o sistema irá pegar o primeiro item que o banco de dados retornar!

. E-commerce para parceiros comerciais

Para a geração de pedidos do processo de parceiros comerciais, (clique aqui para acessar a base de conhecimento que descreve o processo) é necessário informar o campo <CnpjParceiro>?</CnpjParceiro> dentro da tag <informacaoDoSite>, conforme exemplo abaixo:

<informacaoDoSite>
  <Cnpj>?</Cnpj>
  <Token>?</Token>
  <CnpjParceiro>?</CnpjParceiro>
</informacaoDoSite>

FAQ

- "RetornaTodosOsProdutosCadastrados" retorna todos os produtos cadastrado na base de dados referente a loja que foi efetuado a busca? Até mesmo os desativados?

R: Retorna todos os produtos cadastrados, que estejam ativados na loja e estejam configurados para participar da integração do e-commerce.

- "RetornaSomenteProdutosQueSofreramAlteracoes" retorna produtos que sofreram alterações nos últimos dias? Se sim com até quantos dias de alteração? Se não for essa lógica dessa funcionalidade, consegue me informar como funciona exatamente?

R: Retorna todos os produtos que sofreram alteração desde a última consulta deste webservice, inclusive os que foram desativados.

- É possível me enviar um exemplo de retorno (response) de cada um dos serviços da Webservice?:

R: Não conseguimos gerar um exemplo, pois não há ambiente sandbox ou homologação. No entanto, pode ser consumido o webservice do cliente em produção para receber o retorno em XML.

Integração e-Commerce para Desenvolvedores Imprimir