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

Envie ao Coordenador do Projeto as informações a seguir por ambiente, HOMOLOGAÇÃO E PRODUÇÃO:

• URL Ambiente REST: 
• http://{IP}:{PORTA}/dts/datasul-rest/resources/prg/

• Usuário e Senha cadastrado no Datasul (exemplo - usuário: totvssfadt senha: dtsenha14)
• Considerações: de preferência, o usuário e senha deve ser minúsculo e sem nenhum caractere especial.

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

Nesta foi realizado um de-para de todas as rotinas executadas em um cliente Datasul. Serão apresentadas informações como tabela e campo de origem do Datasul, qual endpoint e campos utilizados para trazer os dados via API e em quais tabelas e campos do SFA essas informações serão inseridas.

Abaixo será apresentado também como é feita hoje a organização das transformações utilizadas pela integração. 

Segue um mapeamento de todas entidades integradas pelo Datasul atualmente.

PAIS-UF-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: 

CLIENTE

Os dados das tabelas emitente, cidade e loc-entr do Datasul, são acessados através do endpoint /dts/datasul-rest/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, parceiro_nomeAbrev, parceiro_NaturezaOperacao, contatopessoa, contatopessoaemail, contatopessoatelefone e localENT, localTipoLocalENT e parceiroENT,  do TOTVS SFA com o seguintes campos:

CONDIÇÃO PAGAMENTO

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

ESTOQUE

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

FILIAL

Os dados das tabelas estabelec e cidade do Datasul são acessados através do endpoint /dts/datasul-rest/resources/prg/cdp/v1/establishmentsPublic e serão salvos nas tabelas parceiro, local, localfilial, parceirolocal, parceirotipoparceiro, localtipolocal do TOTVS SFA na seguinte ordem

GRUPO PRODUTO

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

MOEDA

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

NOTA FISCAL

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

*Atualizados na rotina SNotaFiscalProduto

NOTA FISCAL DEVOLUÇÃO

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

PEDIDO

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

*Atualizados na rotina SPedidoProduto

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/cep/v1/productPublic e serão salvos nas tabelas produto, produtogrupoproduto, produtoembalagem e produtofilial do TOTVS SFA com os seguintes campos:

TIPO SITUAÇÃO PEDIDO

A entidade tiposituacaopedido do TOTVS SFA conta com valores fixos:

TABELA PREÇO

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

TABELA PRECO PRODUTO

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:

TIPO COBRANÇA

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

TIPO FRETE 

A entidade tipofrete do TOTVS SFA conta com valores fixos:

TIPO NOTA FISCAL

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

TITULOS À RECEBER

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

TRANSPORTADORA

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

UNIDADE MEDIDA

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

VENDEDOR

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

CFOP

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

CLASSIFICAÇÃO FINANCEIRA TITULO

A entidade classificacaofintitulo do TOTVS SFA conta com valores fixos:

CLASSIFICAÇÃO PARCEIRO

A entidade classificacaoparceiro do TOTVS SFA conta com valores fixos:

GRUPO PARCEIRO

Os dados da tabela mgadm.gr do Datasul são acessados através do /dts/datasul-rest/resources/prg/cdp/v1/customerGroupsPublic e são gravados na tabela grupoparceiro do SFA com os seguintes campos.

LINHA 

Os dados da tabela familia do Datasul são acessados através do /dts/datasul-rest/resources/prg/cep/v1/materialFamiliesPublic e são gravados na tabela linha do SFA com os seguintes campos.

LOCAL IDENTIFICACAO

Os dados que serão salvos na tabela localidentificacao são retirados do próprio SFA utilizando a seguinte consulta:

SELECT
    p.idparceiro,
    p.idnexportadoerp,
    'cnpj' AS idTipoIdentificacao_,
    l.idlocal,
    pj.cnpjprincipal AS documentoIdentificacao,
    l.codigoerp AS codigoERPLocal
FROM
    parceiro p
INNER JOIN pessoajuridica pj ON
    p.idparceiro = pj.idpessoajuridica
    AND pj.cnpjprincipal IS NOT NULL
INNER JOIN parceirolocal pl ON
    pl.idparceiro = p.idparceiro
INNER JOIN LOCAL l ON
    l.idlocal = pl.idlocal
INNER JOIN LOCALTIPOLOCAL LTL ON LTL.IDLOCAL = L.IDLOCAL
INNER JOIN TIPOLOCAL TL ON TL.IDTIPOLOCAL = LTL.IDTIPOLOCAL
WHERE
    TL.SGLTIPOLOCAL <> 'ENT'
    AND L.CODIGOERP IS NOT NULL
UNION
SELECT
    p.idparceiro,
    p.idnexportadoerp,
    'cpf' AS idTipoIdentificacao_,
    l.idlocal,
    pf.cpf AS documentoIdentificacao,
    l.codigoerp AS codigoERPLocal
FROM
    parceiro p
INNER JOIN pessoafisica pf ON
    p.idparceiro = pf.idpessoafisica
    AND pf.cpf IS NOT NULL
INNER JOIN parceirolocal pl ON
    pl.idparceiro = p.idparceiro
INNER JOIN LOCAL l ON
    l.idlocal = pl.idlocal
WHERE
    l.codigoERP IS NOT null
UNION
SELECT
    p.idparceiro,
    p.idnexportadoerp,
    'inscricaoestadual' AS idTipoIdentificacao_,
    l.idlocal,
    l.inscricaoestadual AS documentoIdentificacao,
    l.codigoerp AS codigoERPLocal
FROM
    parceiro p
INNER JOIN parceirolocal pl ON
    pl.idparceiro = p.idparceiro
INNER JOIN LOCAL l ON
    l.idlocal = pl.idlocal
WHERE
    l.codigoERP IS NOT NULL
    AND l.inscricaoestadual IS NOT NULL
UNION
SELECT
    p.idparceiro,
    p.idnexportadoerp,
    'inscricaomunicipal' AS idTipoIdentificacao_,
    l.idlocal,
    l.inscricaomunicipal AS documentoIdentificacao,
    l.codigoerp AS codigoERPLocal
FROM
    parceiro p
INNER JOIN parceirolocal pl ON
    pl.idparceiro = p.idparceiro
INNER JOIN LOCAL l ON
    l.idlocal = pl.idlocal
WHERE
    l.codigoERP IS NOT NULL
    AND l.inscricaomunicipal IS NOT NULL 

OPERAÇÃO

A entidade operacao do TOTVS SFA conta com valores fixos:

PERFIL ACESSO

A entidade perfilacesso do TOTVS SFA conta com valores fixos:

PORTADOR

Os dados da tabela portador do Datasul são acessados através do endpoint /dts/datasul-rest/resources/prg/fin/v1/holderPublic e serão salvos na tabela parceiro do TOTVS SFA com os seguintes campos:

REGIÃO

Os dados da tabela mgadm.regiao do Datasul são acessados através do endpoint /dts/datasul-rest/resources/prg/cdp/v1/regionsPublic e serão salvos na tabela regiao e localregiao do TOTVS SFA com os seguintes campos:

TIPO DOCUMENTO

Os dados da tabela espec_docto do Datasul são acessados através do /dts/datasul-rest/resources/prg/fin/v1/documentTypePublic e são gravados na tabela tipodocumento do SFA com os seguintes campos.

TIPO EMAIL

A entidade tipoemail do TOTVS SFA conta com valores fixos:

TIPO ESTOQUE

A entidade tipoestoque do TOTVS SFA conta com valores fixos:

TIPOLOGIA

Os dados da tabela tipologia do Datasul são acessados através do endpoint /dts/datasul-rest/resources/prg/cdp/v1/salesChannelPublic e são gravados com os seguintes campos.

TIPO PEDIDO

A entidade tipopedido do TOTVS SFA conta com valores fixos:

TIPO PRODUTO

A entidade tipoproduto do TOTVS SFA conta com valores fixos:

TIPO SITUACAÇÃO PEDIDO PRODUTO

A entidade tipositpedidoproduto do TOTVS SFA conta com valores fixos:

TIPO SITUAÇÃO CADASTRO

A entidade tiposituacaocadastro do TOTVS SFA conta com valores fixos:

TIPO TELEFONE

A entidade tipotelefone do TOTVS SFA conta com valores fixos:

TRANSAÇÃO FISCAL

Os dados da tabela cond-pagto do Datasul são acessados através do endpoint /dts/datasul-rest/resources/prg/cdp/v1/paymentTermsPublic e são salvos na tabela TransacaoFiscal 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.

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 clientes novos:

• Situação do cadastro igual à novo (TIPOSITUACAOCADASTRO.SGLTIPOSITUACAOCADASTRO = ‘NOV’);
• Parceiros com filtro de não exportado (PARCEIRO.IDNEXPORTADOERP = 0).
• Parceiros sem codigoERP (PARCEIRO.CODIGOERP IS NULL)

Ou esses filtros caso se trate de uma atualização do cliente:

• Situação do cadastro igual à atualização (TIPOSITUACAOCADASTRO.SGLTIPOSITUACAOCADASTRO = ‘ATU’);
• Parceiros ou Locais com filtro de não exportado (PARCEIRO.IDNEXPORTADOERP = 0 OR P.IDPARCEIRO IN (SELECT IDPARCEIRO FROM PARCEIROLOCAL WHERE IDLOCAL IN (SELECT IDLOCAL FROM LOCAL WHERE IDNEXPORTADOERP = 0)))).
• Parceiros com codigoERP (PARCEIRO.CODIGOERP IS NOT NULL)

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:

PEDIDO

A exportação de pedidos consiste em:

• Cabeçalho e Itens.

Utilizando os seguintes filtros para exportar:

• Pedidos de origem diferente de ERP (PED.SGLORIGEMPEDIDO != 'ERP');
• 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: