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.