Escopo de Integração - Protheus

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

2. HISTÓRICO DE REVISÃO

3. INTEGRAÇÃO DE DADOS

A integração de dados entre TOTVS CRM | SFA e Protheus se dá através de uma API (Application Programming Interface) que utiliza web services com arquitetura REST (Representation State Transfer) para importação de dados (Protheus → TOTVS CRM | SFA) e SOAP (Simple Object Access Protocol) para a exportação de pedidos (TOTVS CRM | SFA → Protheus).

3.1 Horários de execução padrões

Todas as rotinas de integração são executadas conforme um agendamento, que determina os horários em que as rotinas serão executadas. Em servidores Windows, o agendamento é feito através da ferramenta Agendador de Tarefas, que é nativa do sistema operacional, enquanto em servidores Linux o agendamento é feito através de um arquivo Cron, que é o equivalente do agendador de tarefas para sistemas Unix.
Por padrão, os agendamentos de execução das rotinas standard são feitos da seguinte forma: Importação Geral (BLOCO_ALL): Inicia a execução às 6h, repete a cada intervalo de 1h, encerrando as execuções as 20h (expressão cron: 0 4-20 * * *);
Exportação Pedido: Inicia a execução às 6h, repete a cada intervalo de 5min, encerrando as execuções as 20h (expressão cron: */5 4-20 * * *);
Exportação Clientes: Inicia a execução às 6h, repete a cada intervalo de 5min, encerrando as execuções as 20h (expressão cron: */5 4-20 * * *).
Ao ser feito o agendamento, deve ser levado em consideração os recursos de cada servidor, para entender se o agendamento padrão é ou não aderente, e ajustar conforme as necessidades.

3.2 Execuções fora do agendamento:

É possível executar os serviços de integração manualmente, caso necessário, tanto em servidores windows como em servidores linux.
Windows: Como todos os agendamentos são feitos através do Agendador de Tarefas do Windows (Task Scheduler), é possível executá-los a partir do mesmo. É possível também executar o arquivo .bat da integração desejada diretamente da pasta da integração;
Linux: É necessário executar o arquivo .sh da rotina desejada na pasta da integração.

3.3 Importação de dados

A importação de dados do Protheus para o TOTVS CRM | SFA é realizada através de requisições ao método getgenerico presente na API de integração REST.
Este método retorna os registros de uma única tabela do banco de dados do Protheus de forma genérica através de parâmetros enviados na sua requisição.
Método de requisição: GET
URL base: IP e Porta
Nome do método: GETGENERICO
Autenticação: BASIC (se habilitada) ou NO AUTH (se não habilitada)
Exemplo: http://10.50.100.1:8036/rest/wssim3g/getgenerico
Header: 

Body (Request): Vazio

Result: Objeto JSON contendo os dados do retorno da consulta

Parâmetros (Querystring): 

Exemplo de requisição:

http://10.50.100.1:8036/rest/WSSIM3G/getgenerico?table=CC2&field=CC2_CODMU
N,CC2_MUN&limit=100&page=1&order=CC2_EST,CC2_MUN&filter=CC2_EST='PR'

Exemplo de retorno:

{
"result":

{"CC2_EST": "PR","CC2_CODMUN": "00608","CC2_MUN": "ALTO PARANA"},
{"CC2_EST": "PR","CC2_CODMUN": "00905","CC2_MUN": "AMAPORA"},
{"CC2_EST": "PR","CC2_CODMUN": "06704","CC2_MUN": "CRUZEIRO DO SUL"},
{"CC2_EST": "PR","CC2_CODMUN": "07108","CC2_MUN": "DIAMANTE DO NORTE"},
{"CC2_EST": "PR","CC2_CODMUN": "08908","CC2_MUN": "GUAIRACA"},
{"CC2_EST": "PR","CC2_CODMUN": "10300","CC2_MUN": "INAJA"},
{"CC2_EST": "PR","CC2_CODMUN": "11308","CC2_MUN": "ITAUNA DO SUL"},
{"CC2_EST": "PR","CC2_CODMUN": "12603","CC2_MUN": "JARDIM OLINDA"},
{"CC2_EST": "PR","CC2_CODMUN": "13502","CC2_MUN": "LOANDA"},
{"CC2_EST": "PR","CC2_CODMUN": "15002","CC2_MUN": "MARILENA"}
],
"count": 10,
"page": 1
} 

3.4 Blocos de execução

A importação de dados é dividida em blocos, cada blocos contendo uma série de rotinas que giram em torno do mesmo módulo ou tipo de informação, e todos estes blocos por sua vez são contidos em um bloco geral, chamado de BLOCO_ALL, que é executado periodicamente como uma carga geral de informações.

Blocos:

Bloco Commons: Composto de rotina que importam informações mais estáticas, que não dependem de muitos vínculos e não tendem a mudar com frequência, sendo de certa forma informações generalistas no sistema. Exemplo: entidade país, unidade federativa, cidade, tipo parceiro etc.

Bloco Filial: Possui apenas a rotina GETFILIAL, que faz a importação de filiais para o TOTVS CRM | SFA;

Bloco TES: Realiza a importação das informações de TES, com base no tipo de TES utilizado (inteligente ou padrão);

Bloco Vendedor: Importa as informações pertinentes aos usuários e seus vínculos (usuário filia, usuário e-mail etc.);

Bloco Parceiro: É composto das rotinas de integração de transportadoras e de clientes, assim como seus vínculos;

Bloco Produto: Integra todas as informações com relação aos produtos e seus vínculos, assim como informações de tipo de produto, grupo de produto, unidade de medida e embalagem;

Bloco Estoque: Realiza a integração de informações de estoque por produto;

Bloco Preço: Importa as informações de tabelas de preços e as vincula com produtos e locais de clientes.

3.5 Entidades da importação de dados

Abaixo estão descritas todas as entidades que são importadas na integração standard entre Protheus e TOTVS CRM | SFA.

PAIS (Tablea PAIS)

Retorna todos os países cadastrados no Protheus na tabela SYA. 

UNIDADE FEDERATIVA (Tabela UNIDADEFEDERATIVA)

Retorna todas as unidades federativas cadastradas no Protheus na tabela SX5 quando X5_TABELA = '12'. 

CIDADE (Tabela CIDADE)

Retorna todas as cidades cadastradas no Protheus na tabela CC2.

TIPO DE FRETE (Tabela TIPOFRETE)

Retorna todos os tipos de frete cadastrados no Protheus na tabela C0X.

CONDIÇÃO DE PAGAMENTO (Tabela CONDICAOPAGAMENTO)

Retorna todas as condições de pagamento cadastradas no Protheus na tabela SE4.

TIPO DE COBRANÇA (Tabela TIPOCOBRANCA)

Retorna todos os tipos de cobrança cadastrados no Protheus na tabela SX5 quando X5_TABELA = '24'.

REGIÃO (Tabela REGIAO)

Retorna todas as regiões cadastradas no Protheus na tabela SX5 quando X5_TABELA = 'A2'.

SEGMENTO (Tabela SEGMENTO)

Retorna todos os segmentos cadastrados no Protheus na tabela SX5 quando X5_TABELA = 'T3'.

TIPO DE ESTOQUE (Tabela TIPOESTOQUE)

Entidade existente apenas no TOTVS CRM | SFA, fazendo-se necessária para que o estoque tenha pelo menos um tipo.

CLASSIFICAÇÃO DO CLIENTE (Tabela CLASSIFICACAOPARCEIRO)

Entidade existente apenas no TOTVS CRM | SFA, fazendo-se necessária para que o cliente tenha sua respectiva classificação.

PERFIL DE ACESSO (Tabela PERFILACESSO)

Entidade existente apenas no TOTVS CRM | SFA, fazendo-se necessária para que os usuários tenham seu respectivos perfis de acesso.

SITUAÇÃO DO PEDIDO (Tabela TIPOSITUACAOPEDIDO)

Entidade existente apenas no TOTVS CRM | SFA, fazendo-se necessária para que os pedido tenham sua respectiva situação.
Existem três situações que são imprescindíveis para o TOTVS CRM | SFA: NF (não finalizado), PP (pedido pendente) e PA (pedido aberto).
A descrição poderá sofrer alterações, porém a sigla deverá manter-se sempre estas listadas acima.
Existem duas situações que também são comuns à todos os clientes: PF (pedido faturado) e PC (pedido cancelado).
Estas podem sofrer alterações tanto na descrição quanto na sua sigla. 

TIPO DE NOTA FISCAL (Tabela TIPONOTAFISCAL)

Retorna todos os tipos de notas fiscais cadastrados no Protheus na tabela SX5 quando X5_TABELA = 'MQ'.

TES - PADRÃO E INTELIGENTE (Tabela TESPROTHEUS)

O cadastro Tipo de Entrada e Saída (TES) é responsável pela correta classificação dos documentos fiscais de entrada e saída registrados no Protheus.
Seu preenchimento deve ser efetuado com muito cuidado, pois através dele é possível:
● Calcular os tributos pertinentes ao documento registrado (entrada ou saída), bem como, definir sua escrituração nos Livros Fiscais de ISS, ICMS e IPI (integração com Livros Fiscais);
● Controlar a entrada e saída de produtos/valores no estoque (integração com Estoque e Custos, Faturamento e Compras) e atualizar os custos de entrada e saída;
● Incluir automaticamente títulos na carteira a receber (vendas/saída) e na carteira a pagar (compras/entradas) (integração com os ambientes Faturamento e Compras);
● Registrar automaticamente os ativos imobilizados, a partir dos documentos de entrada referentes à compra de ativo fixo (integração com o Ativo Fixo);
● Registrar a relação "Cliente X Produto/Equipamentos" quando há saída de um documento fiscal (integração com o Field Service);
● Agregar despesas ao custo do projeto ou as receitas recebidas (integração com Gestão de Projetos);
● Calcular os tributos relacionados aos documentos de transporte e, quando necessário, calcular os impostos pertinentes ao frete do autônomo (integração com Gestão de Transportes);
● Calcular impostos variáveis relativos à tributação específica, como por exemplo, impostos localizados

Para o TOTVS CRM | SFA, o cliente deverá informar qual tipo de TES utiliza: INTELIGENTE ou PADRÃO.

Dependendo do tipo da TES, a integração irá direcionar sua importação dos dados para a tabela correta.

TES PADRÃO: retorna todas as TES padrões cadastradas no Protheus na tabela SF4.

TES INTELIGENTE: retorna todas as TES inteligentes cadastradas no Protheus na tabela SX5 quando X5_TABELA = 'DJ'.

CADASTRO DE EMPRESAS/FILIAIS (Tabela LOCAL/PARCEIRO/LOCALTELEFONE)

Retorna todas as empresas/filiais do cliente cadastradas no Protheus no arquivo de configuração SM0.

CADASTRO DE USUÁRIOS E/OU REPRESENTANTES (Tabela USUARIO)

Retorna todos os usuários e/ou representantes cadastrados no Protheus na tabela SA3.

CADASTRO DE EMAILS DOS USUÁRIOS E/OU REPRESENTANTES (Tabela USUARIOEMAIL)

Retorna todos os emails cadastrados para os usuários e/ou representantes no Protheus na tabela SA3.

CADASTRO DE TELEFONES DOS USUÁRIOS E/OU REPRESENTANTES (Tabela USUARIOTELEFONE)

Retorna todos os telefones cadastrados para os usuários e/ou representantes no Protheus na tabela SA3.

CADASTRO DE HIERARQUIAS DOS USUÁRIOS E/OU REPRESENTANTES (Tabela USUARIOHIERARQUIA)

Retorna as hierarquias cadastrados para os usuários e/ou representantes no Protheus na tabela SA3.

Pode-se utilizar para a hierarquia os campos A3_SUPER ou A3_GEREN.

CADASTRO DE VÍNCULOS DOS USUÁRIOS E/OU REPRESENTANTES COM SUA FILIAL/EMPRESA (Tabela USUARIOFILIAL)

Retorna a filial/empresa cadastrada para o usuário e/ou representante no Protheus na tabela SA3.

CADASTRO DA TRANSPORTADORA (Tabela LOCAL/PARCEIRO/LOCALTELEFONE/LOCALEMAIL/LOCALFILIAL)

Retorna o cadastro da transportadora no Protheus na tabela SA4.

CADASTRO DO TIPO DO LOCAL DA TRANSPORTADORA (Tabela LOCALTIPOLOCAL)

Retorna o cadastro do tipo do local da transportadora no Protheus na tabela SA4.

CADASTRO DO EMAIL DA TRANSPORTADORA (Tabela LOCALEMAIL)

Retorna o cadastro do e-mail vinculado ao local da transportadora no Protheus na tabela SA4.

CADASTRO DO TELEFONE DA TRANSPORTADORA (Tabela LOCALTELEFONE)

Retorna o cadastro do telefone vinculado ao local da transportadora no Protheus na tabela SA4.

CADASTRO DO LOCAL DA FILIAL DA TRANSPORTADORA (Tabela LOCALFILIAL)

Retorna o cadastro do local da filial da transportadora no Protheus na tabela SA4.

CADASTRO DE PESSOA JURÍDICA DA TRANSPORTADORA (Tabela PESSOAJURIDICA)

Retorna o cadastro dos dados da pessoa jurídica da transportadora no Protheus na tabela SA4.

CADASTRO DO TIPO DE PARCEIRO DA TRANSPORTADORA (Tabela PARCEIROTIPOPARCEIRO)

Retorna o cadastro do tipo do parceiro da transportadora no Protheus na tabela SA4.

CADASTRO DE PARCEIRO (Tabela PARCEIRO)

Retorna o cadastro do parceiro no Protheus na tabela SA1.

CADASTRO DO LOCAL PRINCIPAL DO PARCEIRO (Tabela LOCAL)

Retorna o cadastro do local principal do parceiro no Protheus na tabela SA1.

CADASTRO DO LOCAL DE COBRANÇA DO PARCEIRO (Tabela LOCAL)

Retorna o cadastro do local de cobrança do parceiro no Protheus na tabela SA1.

CADASTRO DO LOCAL DE ENTREGA DO PARCEIRO (Tabela LOCAL)

Retorna o cadastro do local de entrega do parceiro no Protheus na tabela SA1.

CADASTRO DO TIPO DO LOCAL DE COBRANÇA DO PARCEIRO (Tabela LOCALTIPOLOCAL)

Retorna o cadastro do tipo do local de cobrança do parceiro no Protheus na tabela SA1.

CADASTRO DO LOCAL DE COBRANÇA DO PARCEIRO (Tabela PARCEIROLOCAL/LOCALTIPOLOCAL)

Retorna o cadastro do local de cobrança do parceiro no Protheus na tabela SA1.

CADASTRO DO TIPO DO LOCAL DE ENTREGA DO PARCEIRO (Tabela LOCALTIPOLOCAL)

Retorna o cadastro do tipo do local de entrega do parceiro no Protheus na tabela SA1.

CADASTRO DO LOCAL DE ENTREGA DO PARCEIRO (Tabela PARCEIROLOCAL/LOCALTIPOLOCAL)

Retorna o cadastro do local de entrega do parceiro no Protheus na tabela SA1. 

CADASTRO DO TIPO DO LOCAL PRINCIPAL DO PARCEIRO (Tabela LOCALTIPOLOCAL)

Retorna o cadastro do tipo do local principal do parceiro no Protheus na tabela SA1. 

CADASTRO DO LOCAL PRINCIPAL DO PARCEIRO (Tabela PARCEIROLOCAL)

Retorna o cadastro do local principal do parceiro no Protheus na tabela SA1.

CADASTRO DE PESSOA FÍSICA DO PARCEIRO (Tabela PESSOAFISICA)

Retorna o cadastro de pessoa física do parceiro do Protheus na tabela SA1.

CADASTRO DE PESSOA JURÍDICA DO PARCEIRO (Tabela PESSOAJURIDICA)

Retorna o cadastro de pessoa jurídica do parceiro do Protheus na tabela SA1.

CADASTRO DO EMAIL DO PARCEIRO (Tabela LOCALEMAIL)

Retorna o cadastro do e-mail do parceiro vinculado ao local no Protheus na tabela SA1. 

CADASTRO DO TELEFONE DO PARCEIRO (Tabela LOCALTELEFONE)

Retorna o cadastro do telefone do parceiro vinculado ao local do Protheus na tabela SA1.

CADASTRO DA FILIAL DO PARCEIRO (Tabela LOCALFILIAL)

Retorna o cadastro da filial do parceiro vinculado ao local no Protheus na tabela SA1.

CADASTRO DE LIMITE DE CRÉDITO DO PARCEIRO (Tabela LIMITECREDITO)

Retorna o cadastro de limite de crédito do parceiro do Protheus na tabela SA1.

CADASTRO DO TIPO DE PARCEIRO (Tabela PARCEIROTIPOPARCEIRO)

Retorna o cadastro do tipo do parceiro do Protheus na tabela SA1.

CADASTRO DA CONDIÇÃO DE PAGAMENTO DO PARCEIRO (Tabela LOCALCONDICAOPAGAMENTO)

Retorna o cadastro da condição de pagamento do parceiro vinculado ao local do Protheus na tabela SA1.

CADASTRO DO USUÁRIO DO PARCEIRO (Tabela USUARIOLOCAL)

Retorna o cadastro do usuário do parceiro vinculado ao local do Protheus na tabela SA1.

CADASTRO DA IDENTIFICAÇÃO DO LOCAL DO PARCEIRO (Tabela LOCALIDENTIFICACAO)

Retorna o cadastro da identificação do local do parceiro no Protheus na tabela SA1.

CADASTRO DO LOCAL DO TIPO DE COBRANÇA DO PARCEIRO (Tabela LOCALTIPOCOBRANCA)

Retorna o cadastro do tipo de cobrança do parceiro vinculado ao local do Protheus na tabela SA1.

CADASTRO DO PARCEIRO TRANSPORTADOR (Tabela PARCEIROTRANSPORTADOR)

Retorna o cadastro do parceiro transportador do Protheus na tabela SA1.

CADASTRO DO LOCAL DA REGIÃO DO PARCEIRO (Tabela LOCALREGIAO)

Retorna o cadastro da região do parceiro vinculado ao local do Protheus na tabela SA1. 

CADASTRO DO LOCAL SEGMENTO DO PARCEIRO (Tabela LOCALSEGMENTO)

Retorna o cadastro do segmento do parceiro vinculado ao local do Protheus na tabela SA1.

CADASTRO DO TIPO DO PRODUTO (Tabela TIPOPRODUTO)

Retorna o cadastro do tipo do produto do Protheus na tabela SX5 quando X5_TABELA = '02'.

CADASTRO DO GRUPO DO PRODUTO (Tabela GRUPOPRODUTO)

Retorna o cadastro do grupo do produto do Protheus na tabela SBM. 

CADASTRO DA UNIDADE DE MEDIDA (Tabela UNIDADEMEDIDA)

Retorna o cadastro da unidade de medida do Protheus na tabela SAH.

CADASTRO DA EMBALAGEM (Tabela EMBALAGEM)

Retorna o cadastro da embalagem do Protheus na tabela SAH.

CADASTRO DO PRODUTO (Tabela PRODUTO)

Retorna o cadastro do produto do Protheus na tabela SB1. 

CADASTRO DA EMBALAGEM PADRÃO DO PRODUTO (Tabela PRODUTOEMBALAGEM)

Retorna o cadastro da embalagem padrão do produto do Protheus na tabela SB1.

CADASTRO DA EMBALAGEM SECUNDÁRIA DO PRODUTO (Tabela PRODUTOEMBALAGEM)

Retorna o cadastro da embalagem secundária do produto do Protheus na tabela SB1. 

CADASTRO DA FILIAL DO PRODUTO (Tabela PRODUTOFILIAL)

Retorna o cadastro do produto vinculado a filial no Protheus na tabela SB1.

CADASTRO DO TIPO DO PRODUTO (Tabela PRODUTOTIPOPRODUTO)

Retorna o cadastro do tipo do produto do Protheus na tabela SB1.

CADASTRO DO ESTOQUE (Tabela ESTOQUE)

Retorna o cadastro do estoque do Protheus na tabela SB2.

CADASTRO DA TABELA DE PREÇO (Tabela TABELAPRECO)

Retorna o cadastro da tabela de preço do Protheus na tabela DA0. 

CADASTRO DA TABELA DE PREÇO DO PRODUTO (Tablea TABELAPRECOPRODUTO)

Retorna o cadastro da tabela de preço do produto do Protheus na tabela DA1.

CADASTRO DO LOCAL DA TABELA DE PREÇO (Tabela LOCALTABELAPRECO)

RETORNA O CADASTRO DA TABELA DE PREÇO VINCULADO AO LOCAL NO PROTHEUS NA TABELA SA1.

CADASTRO DO PEDIDO (Tabela PEDIDO)

Retorna o cadastro do pedido do Protheus na tabela SC5.

CADASTRO DO PEDIDO DO PRODUTO (Tabela PEDIDOPRODUTO)

Retorna o cadastro do pedido do produto no Protheus na tabela SC6.

CADASTRO DA ENTREGA DO PEDIDO (Tabela PEDIDOENTREGA)

Retorna o cadastro da entrega do pedido no Protheus na tabela SC5 e na tabela SC6.

CADASTRO DA NOTA FISCAL (Tabela NOTAFISCAL)

Retorna o cadastro da nota fiscal do Protheus na tabela SF2. 

CADASTRO DA NOTA FISCAL DO PRODUTO (Tabela NOTAFISCALPRODUTO)

Retorna o cadastro da nota fiscal do produto no Protheus na tabela SF2 e na tabela SD2.

CADASTRO DA SCFOP (Tabela CFOP)

Retorna o cadastro da scfop do Protheus na tabela SD2. 

CADASTRO DA NOTA FISCAL DEVOLUÇÃO (Tabela NOTAFISCAL)

Retorna o cadastro da nota fiscal de devolução do Protheus na tabela SF1.

CADASTRO DA NOTA FISCAL DO PRODUTO DEVOLUÇÃO (Tabela NOTAFISCALPRODUTO)

Retorna o cadastro da nota fiscal de devolução do produto no Protheus na tabela SD1.

CADASTRO DO FINANCEIRO (Tabela FINANCEIROTITULO)

Retorna o cadastro do financeiro do Protheus na tabela SE1.

3.6 Entidades da exportação de dados

Diferentemente da importação de dados, a exportação é feita através de um webservice SOAP.

Método de Requisição: XML SOAP

URL base: http://IP:PORTA/wssim3g/WSSIM3G_INPEDIDO.apw?WSDL

Os únicos parâmetros passados para o webservice são o XML de envio e o campo INLOGIN.

Exemplo de envio de pedido:

XML Pedido

Exemplo de envio de cliente:

PEDIDO

Retorna a exportação da entidade pedido das tabelas PEDIDO, PARCEIRO, CONDICAOPAGAMENTO, PEDIDOENTREGA, LOCAL, PRODUTO, TABELAPRECO, CLASSIFICACAOPARCEIRO, TIPOCOBRANCA, TIPOFRETE, USUARIO. 

Um pedido só é enviado pela integração se atender as seguintes condições:

● Não tenha sido exportado (pedido.idnexportadoerp = 0);
● Esteja pendente (tiposituacaopedido.sgltiposituacaopedido = ‘PP’);
● Não seja de origem ERP (pedido.sglorigempedido <> ‘ERP’);
● Caso possua aprovações, verifica se a aprovação mais recente está aprovada
(tiposituacaoaprovacao.sgltiposituacaoaprovacao = ‘AP’).

Após uma exportação bem-sucedida, duas colunas do pedido serão atualizadas, uma senda a coluna dataSituacao, que recebe a data de exportação, e a outra sendo a coluna observacaoSituacao, que recebe a data de exportação e também armazena o retorno do plugin, no padrão abaixo:

DATA/HORA: DD/MM/YYYY HH24:MI:SS
Pedido incluído com sucesso! Número ERP: XXXXXX

Caso a inclusão de um pedido não seja bem-sucedida, a rotina altera a situação do pedido para “Não Finalizado” novamente, para que ele seja revisado pelo vendedor.

ITENS DO PEDIDO

Retorna a exportação da entidade itens do pedido das tabelas PEDIDOENTREGA, PEDIDOPRODUTO, TIPOPEDIDO, PEDIDO, PRODUTO, TABELAPRECOPRODUTO.

Antes de realizar a consulta de itens do pedido, é validado o tipo de TES utilizado pelo cliente. No caso de TES inteligente, a tag C6_OPER recebe o valor tipopedido.codigo, enquanto a tag C6_TES é enviada vazia. Para TES padrao é feito o oposto, enviando o campo tipopedido.codigo na tag C6_TES e enviando a tag C6_OPER vazia.

CLIENTE

Retorna a exportação da entidade cliente das tabelas PARCEIRO, LOCAL, USUARIOFILIAL, CLASSIFICACAOPARCEIRO, UNIDADEFEDERATIVA, CIDADE, LOCALTELEFONE, CONTATOPESSOA, PESSOAFISICA, PESSOAJURIDICA, LOCALEMAIL, CONDICAOPAGAMENTO, TABELAPRECO.

A rotina standard realiza o envio apenas de clientes que atendam as seguintes condições:
● Local seja do tipo Principal (tipolocal.sgltipolocal = ‘PRI’);
● Local seja ativo (local.idnativo = 1);
● Parceiro não tenha sido exportado (parceiro.idnexportadoerp = 0).
Visto que o campo A1_LOJA é enviado com o valor fixo '1', não se pode enviar mais de um local para cada cliente utilizando a exportação standard, apesar de ser possível realizar o cadastro de multiplos locais através da aplicação.

Por padrão, a rotina envia os clientes como Ativos e sem bloqueios, pois a tag A1_MSBLQL, responsável por determinar se um cliente está ou não bloqueado (1 = sem bloqueios 2 = bloqueado), é enviada com valor fixo '1'.
Após uma exportação de cliente bem-sucedida, é inserido um registro na tabela mensagem, com o usuário admin como remetente e o usuário gerador do cadastro como destinatário, informando do sucesso do envio. Esta mensagem pode ser acessada pelo usuário através do módulo Mensagem nas aplicações web e mobile. É alterada também a coluna observacaoIntegracao, para que contenha a mensagem de sucesso da exportação. Assim que um cliente exportado for inserido no Protheus, o mesmo estará sujeito a importação pelas rotinas de importação.
Uma vez que um cliente foi cadastrado ele pode ser sujeito a alterações feitas pelo usuário através da aplicação TOTVS CRM | SFA, porém estas alterações posteriores não são enviadas para o Protheus através da exportação, pois a integração standard contempla apenas o primeiro envio de um cadastro novo.

CAMPOS ESPECÍFICOS

Nas rotinas de exportação, tanto de pedidos quanto de clientes, é possível realizar a inclusão de campos adicionais para o envio, que não façam parte dos campos padrões do Protheus, sendo campos específicos de cada cliente. Estes campos devem ser inseridos nas consultas SQL que fazem a busca dos demais campos que serão enviados. Por serem campos não contemplados dentro da rotina standard, estes campos adicionais devem ser tratados como customizações e alinhados da forma devida, antes de serem parametrizados como campos específicos.

Após a inclusão dos campos através da consulta SQL, é necessário realizar o mapeamento dos mesmos no XML que será enviado. O mapeamento de campos específicos é feito através da sintaxe abaixo, dentro do step Campos Espec. A estrutura deve ser repetida para cada campo novo.

IF (trim(A1_NOMETAG != "" && A1_NOMETAG != null) { //Verifica se o campo está nulo ou vazio

CAMPO_ESPEC = "";

//Inicia a variável vazia, para que não receba os valores de campos anteriores

CAMPO_ESPEC += "";

//Inicia a estrutura que será levada para o XML final CAMPO_ESPEC += "A1_NOMETAG ";

//Especifica o nome do campo em questão CAMPO_ESPEC += "" + A1_NOMETAG + "";

//Passa o valor do campo em questão CAMPO_ESPEC += "";

//Encerra a estrutura arrayCampoEspec.push(CAMPO_ESPEC); //Passa a estrutura para um array que agrega todos os campos específicos adicionados

}

Após a inclusão de cada campo específico, é feito um laço FOR para inserir as estruturas geradas dentro da tag , utilizando o array que foi montado anteriormente.

Exemplo de estrutura final: 

Esta estrutura é valida tanto para o mapeamento de campos específicos do envio de clientes quanto para o envio de pedidos.

Exemplo prático:

Durante as parametrizações de exportação de pedidos para o cliente X, foi levantada a necessidade do envio de uma tag chamada C6_LOCAL no envio de itens do pedido, que representa o armazém do produto. No TOTVS CRM | SFA, esta informação é persistida no campo produto.complemento, portanto a seguinte linha é adicionada na consulta de pedidoProduto:
CAST(PRODUTO.COMPLEMENTO AS VARCHAR) AS C6_LOCAL

Após a adição do campo na consulta, é criada a sintaxe que irá gerar a estrutura XML do campo, dentro do step CAMPO_ESPEC_ITENS: 

if (trim(c6_local) != "" && c6_local != null) {

CAMPO_ESPEC = "";

CAMPO_ESPEC += "";

CAMPO_ESPEC += "C6_LOCAL";

CAMPO_ESPEC += "" + c6_local + "";

CAMPO_ESPEC += ""; arrayCampoEspec.push(CAMPO_ESPEC); }

Com isso feito, o XML de envio será gerado contendo este novo campo, assim como qualquer outro adicionado desta forma.

TRATAMENTO DE ERROS

As rotinas de exportação são suscetíveis primariamente a dois tipos de erros, um sendo por conta de indisponibilidades por parte do Plugin, e outro sendo por conta de informações errôneas ou faltantes no XML de envio.
A integração valida a existência de um retorno do plugin através do campo de output (INCLUIRCLIENTERESULT ou INCLUIRPEDIDODRESULT ), que recebe o output da requisição de envio. Se este campo estiver nulo, entende-se que o plugin encontrava-se indisponível, e é gravada uma mensagem conforme o exemplo abaixo:

DATA/HORA: 23/03/2020 17:00:00
Webservice do Protheus Indisponível
Código do Cliente:001

Se o campo de output não estiver nulo, é validado se a mensagem de retorno foi de sucesso através da tag C01TPMENSAGEM (se o valor da tag for S, o cliente/pedido foi inserido com sucesso), e se o cliente/pedido não tiver sido inserido com sucesso é utilizada a tag N03MENSAGEM, que contém a mensagem de retorno do plugin, para gravar o registro em nosso banco. Esta tag contém o detalhamento do motivo do XML não ter integrado no Protheus, sendo por falta de informação ou por valores inválidos, conforme exemplo abaixo: 

DATA/HORA: 23/03/2020 17:00:00

AJUDA:OBRIGAT
Um ou mais campos obrigatórios não foram preenchidos. xxxxxxxxxxxxxxxxxx -> xxxxxxxxxx
Endereço
Código do Cliente:001

No caso da exportação de pedidos, estas informações são gravadas na coluna observacaosituacao da tabela pedido, enquanto para a exportação de cliente é criado um registro na tabela mensagem utilizando por padrão o usuário admin como remetente e o usuário gerador do cadastro como destinatário, sendo possível a visualização pelo módulo de mensagem das aplicações web e mobile.