Escopo Integração SFA (ERP Datasul)

INFORMAÇÕES PROPRIETÁRIA

Este documento é de propriedade da Wealth Systems Informática Ltda. Todas as informações contidas aqui são confidenciais e não devem ser copiadas ou divulgadas para quaisquer terceiros sem antes um consentimento formal, por escrito, da Wealth Systems, podendo somente ser divulgada dentro do Cliente para os seus funcionários que estiverem diretamente envolvidos no projeto, o qual este documento relata.
A empresa Cliente será solenemente responsável por assegurar que todos seus funcionários envolvidos estejam de acordo e acatem estas condições e ainda, está intitulado para usar as informações contidas neste documento, somente para propósitos de avaliação. Este documento é versionado e sua estrutura não poderá ser alterada sem o consentimento do Gerente de Projetos da Wealth Systems.

HISTÓRICO DE REVISÃO

INTRODUÇÃO

1 INTEGRAÇÃO DE DADOS

A integração de dados entre TOTVS SFA e Datasul se dá através de uma API (Application Programming Interface) que utiliza web services com arquitetura REST (Representational State Transfer), tanto para a importação de dados (Datasul → TOTVS SFA) como para a exportação de Pedidos e Clientes (TOTVS SFA → Datasul).

1.1 Agendamento De Rotinas

O agendamento varia muito, conforme o poder de processamento de cada servidor, e da quantidade de registros de tráfego.
Foi criado agendamentos padrão nas rotinas de integração, porém, não necessariamente deve ser seguido à risca pelo motivo explicado acima. Nos cenários necessários, agendamos uma carga completa para ser executada durante a noite.

1.2 Importação De Dados

Abaixo estão descritas todas as entidades que são importadas na integração standard entre Datasul e TOTVS SFA, assim como informações relevantes sobre as APIs e transformações desenvolvidas no Pentaho Spoon pelo time de integração da TOTVS.

Método de requisição: GET 

URL base: http://{IP}:{PORTA}/dts/datasul-rest/resources/prg/{TIPO}/v1/{ENTIDADE}

A URL base acima é o endereço base de vários serviços, que serão listados mais abaixo como entidade.

As informações do IP e a PORTA dependem da configuração do ambiente do cliente. O campo TIPO se refere as divisões de serviços da API Nativa Datasul que são: cdp, cep, ftp, pdp, qop, finapi. 

1.3 Requisições De Autenticação

A autenticação utilizada pelas APIs é a Basic Auth que usa a autenticação por um usuário e senha do Datasul e é convertido em um token base 64 no seguinte modelo:

usuario:senha

Convertendo para base64 temos o seguinte resultado: dXN1YXJpbzpzZW5oYQ==

Adicionando a tag Basic na frente temos o token final:

Basic dXN1YXJpbzpzZW5oYQ==

Esta tag é passada no header Authorization do step do Pentaho ou Postman (se for o caso)

Considerações: de preferência, o usuário e senha deve ser minúsculo e sem nenhum caractere especial.

1.4 Requisições Count

Como o nome já sugere, antes de requisitarmos os dados, contamos os registros que nos retornaram nas chamadas a seguir. Dessa maneira dividimos os registros em páginas, limitando a quantidade total por página (geralmente mil registros por página, mas é possível ser configurado rotina a rotina).
Isso deve ser seguido, pois requisições com um volume de retorno muito grande além gerar lentidão, podem derrubar o serviço do plugin.
Para gerar as paginações fazemos uma primeira requisição com um parâmetro chamado totalCount com o valor true, sendo assim o retorno informa o total de registros na entidade no campo totalHits, conforme mostra o Código 1 para que possamos calcular a quantidade de páginas e o número de registros por requisição.

Segue o exemplo:
URL: http://IP:PORTA/dts/datasul-rest/resources/prg/cdp/v1/cityPublic?totalCount=true 

Resultado:

{
"total": 1,
"totalHits": 5595,
"hasNext": true,
"items": [
{
"IBGECode": 5200050,
"regionCode": "CENTRO",
"sigla": "GO246",
"city": "ABADIA DE GOIAS",
"stateCode": "GO",
"countryName": "BRASIL",
"_expandables": [
"state",
"country"
],
"microRegionCode": ""
}
]
}

2 ENTIDADES

2.1 CanalVenda

Os dados da tabela canal-venda do Datasul são acessados através do endpoint /dts/datasulrest/resources/prg/cdp/v1/salesChannelPublic e são gravados na tabela tipologia no TOTVS SFA, com os seguintes campos. 

2.2 Cidade

Os dados das tabelas cidade, pais e unid-feder do Datasul, são acessados através do endpoint /dts/datasulrest/resources/prg/cdp/v1/cityPublic e são salvos nas tabelas cidade, pais e unidadefederativa do TOTVS SFA com os seguintes campos: 

2.3 Cliente

Os dados das tabelas emitente, cidade e loc-entr do Datasul, são acessados através do endpoint/dts/datasulrest/resources/prg/cdp/v1/customerPublic e são salvos nas tabelas parceiro, local, localtipolocal, parceirolocal, parceirotransportador, parceirogrupoparceiro, pessoafisica, pessoajuridica, localemail, parceirotipoparceiro, limitecredito, localtelefone, usuariolocal, localtipologia, localtabelapreco, localcandicaopagamento, contatopessoa, contatopessoaemail, contatopessoatelefone do TOTVS SFA com o seguintes campos:

2.4 CondicaoPagamento

Os dados da tabela cond-pagto do Datasul são acessados através do endpoint /dts/datasulrest/resources/prg/cdp/v1/paymentTermsPublic e são salvos na tabela condicaopagamento do TOTVS SFA com os seguintes campos: 

2.5 Estoque

Os dados da tabela saldo-estoq do Datasul são acessados através do endpoint /dts/datasulrest/resources/prg/cdp/v1/stockBalancePublic e serão salvos na tabela estoque do TOTVS SFA com os seguintes campos: 

2.6 Filial

Os dados das tabelas estabelec e cidade do Datasul são acessados através do endpoint /dts/datasulrest/resources/prg/cdp/v1/establishmentsPublic e serão salvos nas tabelas parceiro, local, localfilial, parceirolocal, parceirotipoparceiro, localtipolocal do TOTVS SFA com os seguintes campos:

2.7 GrupoProduto

Os dados da tabela grup-estoque do Datasul são acessados através do endpoint /dts/datasulrest/resources/prg/cdp/v1/inventoryGroupsPublic e serão salves na tabela grupoproduto do TOTVS SFA com o os seguintes campos:

2.8 Material

Os dados da tabela familia do Datasul são acessados através do endpoint /dts/datasulrest/resources/prg/cdp/v1/materialFamiliesPublic e serão salvos na tabela linha do TOTVS SFA com os seguintes campos: 

2.9 Moeda

Os dados das tabelas moeda e cotacao do Datasul são acessados através do endpoint /dts/datasulrest/resources/prg/cdp/v1/currencyPublic e serão salvos nas tabelas indexador e cotacaoindexador do TOTVS SFA com os seguintes campos:

2.10 NotaFiscal

Os dados das tabelas nota-fiscal, transporte, it-nota-fisc, natur-oper e item do Datasul são acessados através do endpoint/dts/datasulrest/resources/prg/cdp/v1/invoicePublic e serão salvos nas tabelas notafiscal e notafiscalproduto do TOTVS SFA com os seguintes campos:

2.11 NotaFiscal (Devolução)

Os dados da tabela devol-cli do Datasul, são acessados através do endpoint /dts/datasulrest/resources/prg/cdp/v1/returnInvoicePublic e serão salvos na tabela notafiscal e notafiscalproduto do TOTVS SFA com os seguintes campos:

2.12 Pedido

Os dados da tabela pedido do Datasul, são acessados através do endpoint /dts/datasulrest/resources/prg/cdp/v1/ordersPublic e serão salvos na tabela pedido, pedidoproduto e pedidoentrega do TOTVS SFA com os seguintes campos:

2.13 Produto

Os dados das tabelas item, alternativo, item-caixa e item-uni-estab do Datasul são acessados através do endpoint /dts/datasul rest/resources/prg/cdp/v1/productPublic e serão salvos nas tabelas produto, produtogrupoproduto, produtoembalagem do TOTVS SFA com os seguintes campos:

2.14 SituacaoPedido

A entidade situacaopedido do TOTVS SFA conta com valores fixos.

2.15 Tabela Preco

Os dados da tabela tb-preco do Datasul são acessados através do endpoint /dts/datasulrest/resources/prg/cdp/v1/priceTablePublic e serão salvos na tabela tabelapreco do TOTVS SFA com os seguintes campos:

2.16 TabelaPrecoProduto

Neste adapter deverão ser geradas as informações dos produtos das tabelas de preço. Tabela preco-item e item-uni-estab, são acessados através do endpoint /dts/datasul-rest/resources/prg/cdp/v1/priceItemPublic, e serão salvos na tabela tabelaprecoproduto do TOTVS SFA com os seguintes campos: 

2.17 TipoCobranca

Os dados da tabela cart_bcia do Datasul são acessados através do endpoint /dts/datasulrest/resources/prg/cdp/v1/portfolioPublic e serão salvos na tabela tipocobranca do TOTVS SFA com os seguintes campos:

2.18 TipoFrete

A entidade tipofrete do TOTVS SFA conta com valores fixos,

2.19 TipoNotafiscal

Os dados da tabela cfop-natur do Datasul são acessados através do endpoint /dts/datasulrest/resources/prg/cdp/v1/transactionTypesPublic e serão salvos na tabela tiponotafiscal do TOTVS SFA com os seguintes campos: 

2.20 TituloReceber

Os dados das tabelas tit-acr e espec_docto do Datasul são acessados através do endpoin/dts/datasulrest/resources/prg/cdp/v1/receivableDocumentPublic e serão salvos na tabela financeirotitulo do TOTVS SFA com os seguintes campos:

2.21 Transportadora

Os dados da tabela transporte e cidade do Datasul são acessados através do endpoint /dts/datasulrest/resources/prg/cdp/v1/carriersPublic e serão salvos nas tabelas parceiro, local, parceirolocal, localtelefone, parceirotipoparceiro, localtipolocal do TOTVS SFA com os seguintes campos:

2.22 UnidadeMedida

Os dados da tabela tab-unidade do Datasul são acessados através do endpoint /dts/datasulrest/resources/prg/cdp/v1/unityMeasuresPublic e serão salvos na tabela unidademedida do TOTVS SFA com os seguintes campos: 

2.23 Vendedor

Os dados da tabela repres do Datasul são acessados através do endpoint /dts/datasulrest/resources/prg/cdp/v1/representativesPublic e serão salvos na tabela usuario, usuariotelefone, usuarioemail do TOTVS SFA com os seguintes campos: 

3 EXPORTAÇÃO DE DADOS

Assim como na importação, o layout de exportação de pedidos e clientes é o mesmo (envio/retorno). Abaixo trataremos da exportação de clientes e pedidos.

3.1 Clientes

A exportação de clientes consiste em:

● 1 endereço principal (TIPOLOCAL = PRI);
● 1 endereço de cobrança (TIPOLOCAL = COB);
● N endereços de entrega (TIPOLOCAL = COB).

Utilizando os seguintes filtros para exportar:

● Situação do cadastro igual à novo (SGLTIPOSITUACAOCADASTRO = ‘NOV’);
● Parceiros com filtro de não exportado (IDNEXPORTADOERP = 0).

Considerações importantes:

● Caso o cliente não exporte devido à alguma validação do Datasul ou erro da API, o mesmo será reaberto
(SGLTIPOSITUACAOCADASTRO = ‘REP’) e uma mensagem será enviada para o usuário cadastrante
(PARCEIRO.IDUSUARIOGERADOR);
● Ao ser reaberto, o mesmo deverá ser analisado e novamente gravado para novo.

Abaixo segue o DE/PARA dos campos:

3.2 Pedidos

A exportação de pedidos consiste em:

● Cabeçalho e Itens.

Utilizando os seguintes filtros para exportar:

● Pedidos feitos na WEB e no Android;
● Pedidos não exportados (IDNEXPORTADOERP = 0);
● Pedidos sem codigoerp preenchido;
● Pedidos com situações existentes no Datasul ('1', '2', '3', '4', '5', '6', '7');
● Pedidos que não contenham pendências de aprovação;
● Pedidos com situação igual à pendente (SGLTIPOSITUACAOPEDIDO = ‘PP’).

Considerações importantes:

● Caso o pedido não exporte devido à alguma validação do Datasul ou erro da API, o mesmo será reaberto
(SGLTIPOSITUACAOPEDIDO = ‘NF’) e uma mensagem será enviada para o usuário cadastrante
(PEDIDO.IDUSUARIOPROFISSIONAL);
● Ao ser reaberto, o mesmo deverá ser analisado e finalizado.

Abaixo segue o DE/PARA dos campos: