Integração com o ERP Sankhya

1 Introdução

O que é a integração?

A integração com o ERP Sankhya é uma plataforma desenvolvida pela Ploomes para realizar operações de comunicação entre Ploomes e Sankhya.

O que a integração faz?

A integração realiza importação e exportação de dados das entidades principais integradas e também realiza consultas em tempo real no Sankhya em algumas entidades de apoio.

Como funciona a integração?

A integração é composta por serviços de API que são acionados sob demanda para criar e editar as regras de integração e realizar a comunicação de dados através dos serviços de API’s do Sankhya e API’s do Ploomes.

---

2 Escopo Geral

A integração realiza importação e exportação de cadastros básicos de operação e também dos documentos comerciais gerados entre as plataformas. No entanto, existem entidades específicas do Sankhya que são integradas e outras que são apenas consultadas como apoio para as operações no Ploomes.

2.1 Entidades integradas e vias de integração possíveis

Abaixo estão listadas as entidades integradas e suas vias de integração possíveis (exportação e/ou importação).

2.2 Entidades Sankhya de Apoio

As entidades a seguir não estão diretamente integradas ao Ploomes, gerando cadastros no Ploomes como as entidades integradas detalhadas acima, mas são utilizadas para consultas ao Sankhya que trazem informações para o Ploomes.

---

3 Configuração

3.1 Primeira configuração

3.1.1 Habilitação da integração

Para conseguir habilitar a integração, é necessário que o módulo da Integração Sankhya esteja ativo na conta Ploomes. Com o módulo ativo, é possível visualizar nas configurações do Ploomes, na tela de Integrações Plug & Play, a integração Sankhya.

Ao abrir a tela de Integrações Plug & Play vão ser listadas diversas integrações possíveis, inclusive a integração Sankhya.

Na tela de “Integrações plug and play”, se o módulo da Integração Sankhya estiver ativo para a conta Ploomes, é possível iniciar a habilitação da integração Sankhya.

Ao abrir a tela de configuração da integração Sankhya, é aberta a tela de autorização da integração. Nessa tela, é necessário inserir o Token de integração - este token é gerado no ambiente de produção do Sankhya - e realizar a validação do Token. Nessa validação, a integração faz uma consulta simples ao Sankhya para garantir que será possível logar no Sankhya e que será possível trazer os dados do Sankhya para o Ploomes.

Na tela inicial de habilitação da integração é necessário inserir um Token do ambiente Sankhya de produção gerado para a aplicação CRM Ploomes. Após inserir o Token, é necessário realizar uma Validação e posteriormente, caso a validação seja bem sucedida, a Habilitação da integração. Se o Token for válido, ficará disponível o botão “Habilitar integração” que deve ser acionado para prosseguir com a configuração.

E então, com a habilitação da integração concluída, o usuário administrador é direcionado para a tela de configuração da integração.

3.1.2 Autenticação e acesso ao Sankhya

Após a validação do token e habilitação da integração, a integração passa a ter acesso ao Sankhya para as entidades configuradas para o usuário de integração. A autenticação do usuário de integração é feita através de um serviço de login via API: Serviço de Autenticação via Json.

Ao realizar o login no Sankhya integrado, é possível realizar as ações necessárias de consulta, edição e envio de dados entre Ploomes e Sankhya. O usuário de integração fica com sessão ativa no Sankhya, mas consome não compete com as sessões de usuários normais.

Os usuários de integração tem suas sessões expiradas no Sankhya assim como qualquer outro usuário. Portanto, a integração inicia novas seções a cada vez que tem sua sessão interrompida, mantendo sempre um BearerToken principal e outro reserva válido.

---

---

3.1.3 Gatilhos de ação

Os gatilhos de ação são parâmetros True/False configurados na integração para determinar o acionamento ou não de determinados padrões de comportamentos.

Os gatilhos são a forma do usuário administrador determinar se determinadas ações devem ocorrer pela integração ou não.

De forma geral, os gatilhos de ação vão determinar se cadastros serão importados e/ou exportados, e se essas importações e/ou exportações serão realizadas para qualquer criação de cadastro e/ou para qualquer edição de cadastro.

Abaixo, exemplo de gatilho para importação de Parceiros Cliente PJ ativo na configuração.

3.1.4 Filtros de integração

Os filtros de integração são regras pré-definidas na integração para aplicar filtros na importação e exportação de cadastros, selecionando melhor os dados que serão integrados.

Os filtros de integração são uma ferramenta fundamental para que a integração se adapte à necessidade de uso da integração na conta Ploomes, pois permite a criação de regras de filtros totalmente dinâmicas.

Os filtros de integração podem ser de dois tipos:

• Filtros de recebimento (ou Filtros de importação): esses filtros são configurados a cada seção de entidade integrada para criar filtros dinâmicos com base nos campos filtráveis da entidade de origem no Sankhya. Então, com base em campos da entidade no Sankhya, é possível definir regras de filtragem para restringir ou selecionar quais dados serão recebidos do Sankhya no Ploomes.

• Filtros de envio (ou Filtros de exportação): esses filtros são configurados a cada seção de entidade integrada para criar filtros dinâmicos com base nos campos filtráveis da entidade de origem no Ploomes. Então, com base nos campos da entidade no Ploomes, é possível definir regras de filtragem para restringir ou selecionar quais dados serão enviados do Ploomes para o Sankhya.

Os filtros de integração são aplicados tanto na carga de dados inicial da integração quanto durante a operação normal durante o uso da integração e também afetam todos os cadastros do Ploomes e do Sankhya, mesmo os cadastros que já estão integrados.

Os filtros de integração são customizáveis e permitem diversas condições de filtro com base no tipo de campo que podem ser combinadas em múltiplas seções de regras de “E” e “OU”. Não é possível realizar fieldpath nos filtros de recebimento, isto é, não é possível utilizar campos de entidades relacionadas a entidade integrada na criação do filtro de integração.

3.1.5 Mapeamento de campos

O mapeamento de campos é o processo de definir a correspondência entre os campos de duas bases de dados ou sistemas diferentes, garantindo que as informações sejam transferidas corretamente entre eles.

No contexto da integração entre o Ploomes e o Sankhya, esse mapeamento determina quais campos do Ploomes serão sincronizados com os respectivos campos do Sankhya, respeitando os formatos e regras de cada sistema. Por exemplo, um campo de "Nome do Cliente" no Ploomes pode ser vinculado ao campo "Nome Parceiro" no Sankhya, garantindo que os dados sejam corretamente replicados e atualizados entre as plataformas.

Na configuração do mapeamento de campos da integração temos os tipos de mapeamento e as vias de integração dos campos.

Tipos de Mapeamento

Os tipos de mapeamento existentes determinam como é o comportamento de mapeamento específico de alguns campos. Os tipos são definidos abaixo:

Mapeamento fixo

Os mapeamento fixos são aqueles em que os pares de campos (Sankhya e Ploomes) são definidos por padrão na integração. Esses mapeamentos incluem campos obrigatórios do Sankhya que já possuem campos equivalentes nativos no Ploomes.

Os mapeamentos fixos são obrigatórios e não podem ser removidos da integração.

Mapeamento de escolha

Os mapeamentos fixos são aqueles em que o campo de origem no Sankhya é obrigatório mas não necessariamente já exista um campo nativo no Ploomes equivalente. Portanto, nesses mapeamentos é possível escolher qual o campo do Ploomes será mapeado com o campo do Sankhya.

Por padrão, esses campos do Ploomes terão um campo sugerido pela integração. Mas é possível alterá-los na configuração do mapeamento.

Os mapeamentos de escolha são obrigatórios e não podem ser removidos da integração.

Mapeamento customizado

Os mapeamentos customizados são aqueles em que o usuário administrador pode adicionar novas relações de campos para mapeamento conforme a necessidade de uso da integração. Portanto, é possível mapear os campos de origem da entidade Sankhya com qualquer campo do Ploomes (nativos ou dinâmicos).

Por padrão, ao adicionar uma nova relação de campos, o Ploomes não irá sugerir um campo de mapeamento. No entanto, é possível selecionar um campo existente no Ploomes para mapeamento ou criar um campo dinâmico para mapeamento.

É possível mapear campos adicionais criados na entidade principal do Sankhya.

No mapeamento customizado, só é possível mapear os campos do Sankhya que existem na entidade principal integrada. Ou seja, campos existentes em entidades relacionadas não podem ser mapeados, bem como campos virtuais do Sankhya que não existem na entidade Sankhya também não podem ser mapeados.

Os mapeamentos customizados são opcionais e podem ser removidos da integração.

Exemplo de apresentação do mapeamento na seção de configuração de Produtos. No caso da imagem, estão destacados o formato de apresentação dos mapeamentos fixo, de escolha e customizado.

Vias de integração dos campos mapeados

Para cada par de campos mapeados existe uma via de integração desses campos que deve ser definida.

As possibilidades são:

• Sankhya < Ploomes: valor do campo é apenas enviado do Ploomes para o Sankhya

• Sankhya > Ploomes: valor do campo é apenas recebido do Sankhya no Ploomes

• Sankhya <> Ploomes: valor do campo é enviado do Ploomes para o Sankhya e também é recebido do Sankhya no Ploomes.

Para a maior parte dos campos mapeados a integração pré-define uma via de integração dos campos - que não é editável, no entanto, para alguns casos é possível alterar as vias de integração.

Exemplo de vias de integração de campos na seção de Contato de Cliente. Alguns pares de campos tem sua via pré-definida e outros tem sua via sugerida, podendo alterá-la.

Mapeamento de campos de tabelas complementares

A partir da V3 da integração Sankhya é possível realizar o mapeamento de campos de tabelas complementares, conforme descrito no artigo https://suporte.ploomes.com/pt-BR/articles/14367098.

Compatibilidade por Tipos de Campos

Para o mapeamento de campos é possível selecionar somente os campos compatíveis com base na definição abaixo:

Observação importante: campos de mapeamentos fixos não podem ter o seu tipo de campo para o campo Ploomes mapeado alterado.

Particularidades do mapeamento de campos de opções pré-cadastradas

Para o mapeamento de campos do tipo opções pré-cadastradas é necessário realizar uma compatibilização das opções existentes no Ploomes.

As opções pré-cadastradas do Ploomes são compatibilizadas apenas na ativação da integração ou na reativação da integração ou na aplicação de edição da integração. Portanto, se forem criadas novas opções pré-cadastradas no Sankhya em algum campo mapeado, existem 3 formas de realizar a importação dessa nova opção:

• Desativando e reativando a integração;

• Ao editar a integração, clicando no botão de Sincronizar da seção, salvando a seção da entidade em questão e aplicando as edições realizadas na integração;

• Importando algum cadastro que possua o campo com a nova opção pré-cadastrada preenchida no Sankhya.

Existe uma premissa básica de que as opções pré-cadastradas no campo do Sankhya irão prevalecer sobre as opções pré-cadastradas no campo do Ploomes. Essa regra segue a seguinte lógica:

• Caso o campo do Ploomes não tenha nenhuma opção cadastrada ainda, ele recebe as opções do Sankhya;

• Caso o campo do Ploomes possua uma ou mais opções cadastradas:

  • As opções que existem no campo Ploomes e não existem no campo Sankhya serão excluídas do campo Ploomes;

  • As opções que existem no campo Ploomes e que tenham exatamente o mesmo “nome da opção” e “chave de identificação da opção” que as opções do campo Sankhya serão mantidas no campo Ploomes;

  • As opções que existem no campo Ploomes e que tenham apenas o mesmo “nome da opção” mas “chave de identificação da opção” diferentes serão excluídas do campo Ploomes.

  • As opções que existem no campo do Sankhya e que não existem no campo Ploomes serão criadas no campo Ploomes.

É importante estar atento a atualizações realizadas em nomes de campos, obrigatoriedades e opções pré-cadastradas em campos mapeados. O usuário administrador do Ploomes e do Sankhya pode alterar o nome de campos, apagar campos, alterar sua obrigatoriedade (apenas para campos dinâmicos) e também alterar - incluindo ou removendo - as opções pré-cadastradas (apenas para campos dinâmicos). Essas alterações podem impactar diretamente a integração.

Se as edições forem realizadas antes de a integração ser ativada, as alterações podem ser consideradas no mapeamento. Caso as alterações sejam realizadas com a integração ativa, pode ser necessário realizar uma nova compatibilização dos cadastros de opções pré-cadastradas ou alterar o mapeamento dos campos.

---

---

3.1.6 Configurando os cadastros base

Os cadastros base da integração são as regras de pares de entidades básicas que suportam toda a operação no CRM.

Portanto, configuramos os seguintes pares de entidades Sankhya <> Ploomes:

Em cada seção de pares de entidade para os cadastros base da integração, é necessário configurar os gatilhos, filtros e mapeamento. Conforme exemplo abaixo:

Durante a configuração é possível sincronizar metadados do Sankhya. Essa ação é acionável por seção, e permite atualizar os dados de opções pré-cadastradas existentes no Sankhya para criação de filtros de recebimento e também atualiza os campos existentes na entidade do Sankhya integrada.

Após configurar as seções, o modal informativo existe o texto Configurado nas seções que já foram salvas e Não configurado nas seções ainda não salvas.

A seção de cadastros base é extremamente importante, pois impacta diretamente o uso dos cadastros de operação pela integração. Por exemplo: para o sucesso na importação de um Orçamento do Sankhya como Proposta no Ploomes, é necessário que os Produtos, o Parceiro e o Vendedor responsável já estejam integrados no Ploomes.

Após configurar todas as seções de pares de entidades que são a base da integração, é preciso configurar os cadastros de operação.

3.1.7 Configurando os cadastros de operação

Os cadastros de operação da integração são as regras de pares de entidades de documentos (Propostas e Vendas no Ploomes) que registram toda a operação comercial no CRM e as TOP’s do Sankhya que serão utilizadas no Ploomes.

Portanto, configuramos os seguintes pares de entidades Sankhya <> Ploomes:

Configuração de Proposta (Orçamento) e de Venda (Pedido de Venda e Nota de Venda)

Nas seções de Propostas e Vendas, as configurações são as mesmas realizadas para os cadastros base, em que configuramos os gatilhos, filtros e mapeamento dos campos que serão enviados e/ou recebidos entre as entidades.

Na configuração de Propostas, dado que no Ploomes uma Proposta precisa estar vinculada a um Negócio, é necessário escolher em qual estágio específico e em qual funil que o Negócio gerado automaticamente a partir de Orçamentos do Sankhya sejam salvos. É possível determinar qual funil e estágio do funil em que o Negócio será gerado.

Na configuração de Vendas, dado que no Ploomes é opcional o vínculo de uma venda com um Negócio, é possível escolher se os Pedidos de Venda e/ou Notas de Venda recebidos do Sankhya no Ploomes serão vinculados a um Negócio gerado automaticamente ou não. Se sim, é possível determinar qual funil e estágio do funil em que o Negócio será gerado.

Nos mapeamentos das entidades de Orçamento e Pedido de Venda/Nota de Venda existem regras específicas de mapeamento que influenciam na integração e precisam ser configuradas.

Configuração de Tipos de Operação (TOP)

Na seção de configuração de TOP é preciso determinar a relação de TOP’s atribuídas para cada tipo de documento do Sankhya (Proposta, Pedido de Venda e Nota de Venda) que serão utilizadas no Ploomes como opção para seleção e também determinar qual o modelo de documento deve ser utilizado para cada TOP.

Na seção de relacionamento de TOP com o tipo de documento, é possível selecionar mais de uma TOP por tipo de documento.

Na configuração de TOP’s por entidade são listadas as TOP’s com base no Tipo de Movimento configurado no Sankhya. Para Orçamentos e Pedidos de Venda são listadas todas as TOP’s ativas com exceção das que possuem o Tipo de Movimento (TIPMOV) = “V”. As TOP’s de Tipo de Movimento = “V” só são exibidas como opção para as Notas de Venda.

Somente serão habilitadas para configuração de TOP’s os tipos de documentos configurados em alguma via de ação da integração. Ou seja, caso não estejam ativos gatilhos de Pedido de Venda (exportação ou importação), não será habilitada a configuração de relacionamento de TOP com o tipo de documento Sankhya.

Essa definição do relacionamento da TOP com os tipos de documento, determina que ao importar um documento do Sankhya, se o documento foi gerado com uma TOP relacionada com Proposta do Ploomes, será importada como Proposta, assim como para os demais documentos (Pedido de Venda e Nota de Venda).

Ao gerar um documento no Ploomes, Proposta ou Venda, somente estarão disponíveis para seleção as TOP’s configuradas para aquele tipo de documento do Ploomes. Se estiver gerando uma Proposta, serão listadas as TOP’s de Orçamento, e se estiver gerando uma Venda, serão listadas as TOP’s de Pedido de Venda. Como não é possível exportar Notas de Venda do Ploomes para o Sankhya, não são listadas as TOP’s de Notas de Venda ao gerar uma Venda no Ploomes.

Após determinar os relacionamentos de TOP e tipo de documento Sankhya, é preciso realizar o mapeamento dessas TOP’s selecionadas com os Modelos de Documento do Ploomes a serem utilizados.

Com a conclusão da configuração e salvamento das seções dos pares de entidade de Proposta e Venda e também dos Tipos de Operação para a integração, os cadastros de operação estão prontos.

3.1.8 Configurando as consultas em tempo real

A integração realiza algumas consultas em tempo real ao Sankhya via API e, portanto, é necessária a configuração dessas consultas.

Por padrão, a integração realiza a pré-configuração automaticamente ao habilitar a integração.

Para que as consultas em tempo real funcionem, é necessária a criação de campos do tipo desenvolvedor no Ploomes. Esses campos possuem fórmulas que são criadas automaticamente pela integração. Essas fórmulas indicam quais campos serão enviados no payload de requisição da consulta em tempo real ao Sankhya e quais campos receberão os retornos dessa consulta.

Ao habilitar a integração, os mapeamentos de campos de consulta em tempo real são criados automaticamente com suas respectivas fórmulas. Não é possível desabilitar os mapeamentos de consulta em tempo real. Por padrão, como se trata de um mapeamento de consulta ao Sankhya, a via de integração desses campos é definida por padrão como Sankhya > Ploomes e não pode ser alterada.

A configuração das consultas em tempo real estão dentro das seções de Proposta e Venda, pois as consultas são referentes a essas entidades.

Portanto, são configuradas consultas pertinentes para a geração de Propostas e Vendas no Ploomes. Essas consultas são detalhadas abaixo:

Proposta

Para as consultas na tela de geração de Propostas, são configurados os seguintes campos de consulta a dados da Proposta:

• Detalhes financeiros do cliente (Sankhya): este campo retorna os dados de limites de crédito e saldos financeiros do Clientes selecionado na Proposta e integrado a um Parceiro no Sankhya em um campo multilinha.

• Detalhes restrições da TOP (Sankhya): este campo retorna os dados de restrições/exceções da TOP selecionada na configuração da integração em um campo multilinha.

Produto da Proposta

Para as consultas na tela de geração de Propostas, são configurados os seguintes campos de consulta a dados de Produto da Proposta:

• Detalhes de estoque (Sankhya): este campo recebe alguns dados de estoque do Produto/Serviço do Sankhya em um campo multilinha que pode ser visualizado como tabela.

• Valor unitário (Sankhya): este campo recebe o valor unitário do respectivo Produto/Serviço integrado do Sankhya conforme a precificação de sua tabela de preço.

• Produto integrado (Sankhya): este campo recebe um valor de True/False para determinar se um Produto da Proposta está integrado a um Produto/Serviço do Sankhya.

E também, especificamente para a consulta de impostos de Produto da Proposta, são configurados os seguintes dados:

• ICMS Alíquota (Sankhya): este campo recebe o valor da alíquota do imposto ICMS.

• ICMS Valor (Sankhya): este campo recebe o valor do imposto ICMS.

• ICMS Base (Sankhya): este campo recebe o valor base do imposto ICMS.

• IPI Alíquota (Sankhya): este campo recebe o valor da alíquota do imposto IPI.

• IPI Valor (Sankhya): este campo recebe o valor do imposto IPI.

• IPI Base (Sankhya): este campo recebe o valor base do imposto IPI.

• ISS Alíquota (Sankhya): este campo recebe o valor da alíquota do imposto ISS.

• ISS Valor (Sankhya): este campo recebe o valor do imposto ISS.

• ISS Base (Sankhya): este campo recebe o valor base do imposto ISS.

• ST Alíquota (Sankhya): este campo recebe o valor da alíquota do imposto ST.

• ST Valor (Sankhya): este campo recebe o valor do imposto ST.

• ST Base (Sankhya): este campo recebe o valor base do imposto ST.

• FCP Valor (Sankhya): este campo recebe o valor do imposto FCP.

• DIFAL Valor UF Remetente (Sankhya): este campo recebe o valor do imposto DIFAL UF Remetente.

• DIFAL Valor UF Destino (Sankhya): este campo recebe o valor do imposto DIFAL UF Destino.

Venda

Para as consultas na tela de geração de Vendas, análogo à seção de Propostas, são configurados os seguintes campos de consulta a dados da Proposta:

• Detalhes financeiros do cliente (Sankhya): este campo retorna os dados de limites de crédito e saldos financeiros do Clientes selecionado na Venda e integrado a um Parceiro no Sankhya em um campo multilinha.

• Detalhes restrições da TOP (Sankhya): este campo retorna os dados de restrições/exceções da TOP selecionada na configuração da integração em um campo multilinha.

Produto da Venda

Para as consultas na tela de geração de Venda, análogo à seção de Propostas, são configurados os seguintes campos de consulta a dados de Produto da Venda:

• Detalhes de estoque (Sankhya): este campo recebe alguns dados de estoque do Produto/Serviço do Sankhya em um campo multilinha que pode ser visualizado como tabela.

• Valor unitário (Sankhya): este campo recebe o valor unitário do respectivo Produto/Serviço integrado do Sankhya conforme a precificação de sua tabela de preço.

• Produto integrado (Sankhya): este campo recebe um valor de True/False para determinar se um Produto da Venda está integrado a um Produto/Serviço do Sankhya.

E também, especificamente para a consulta de impostos de Produto da Venda, são configurados os seguintes dados:

• ICMS Alíquota (Sankhya): este campo recebe o valor da alíquota do imposto ICMS.

• ICMS Valor (Sankhya): este campo recebe o valor do imposto ICMS.

• ICMS Base (Sankhya): este campo recebe o valor base do imposto ICMS.

• IPI Alíquota (Sankhya): este campo recebe o valor da alíquota do imposto IPI.

• IPI Valor (Sankhya): este campo recebe o valor do imposto IPI.

• IPI Base (Sankhya): este campo recebe o valor base do imposto IPI.

• ISS Alíquota (Sankhya): este campo recebe o valor da alíquota do imposto ISS.

• ISS Valor (Sankhya): este campo recebe o valor do imposto ISS.

• ISS Base (Sankhya): este campo recebe o valor base do imposto ISS.

• ST Alíquota (Sankhya): este campo recebe o valor da alíquota do imposto ST.

• ST Valor (Sankhya): este campo recebe o valor do imposto ST.

• ST Base (Sankhya): este campo recebe o valor base do imposto ST.

• FCP Valor (Sankhya): este campo recebe o valor do imposto FCP.

• DIFAL Valor UF Remetente (Sankhya): este campo recebe o valor do imposto DIFAL UF Remetente.

• DIFAL Valor UF Destino (Sankhya): este campo recebe o valor do imposto DIFAL UF Destino.

---

---

3.2 Alterações de configuração após a primeira ativação

Com a integração ativa na conta Ploomes, é possível realizar 3 operações de alteração na configuração. Essas alterações afetam diretamente toda a conta e uso da integração, assim como a configuração.

As alterações de configuração possíveis são as seguintes:

3.2.1 Editando a integração

Após a ativação da integração na conta, ao abrir a tela de configuração da integração Sankhya no Ploomes, será exibida a tela de configuração com a tela de consulta das seções de configuração cadastradas.

Nesta tela, sem utilizar um dos botões de ação não é possível realizar alterações, apenas consulta das seções configuradas.

No entanto, estarão disponíveis dois botões de ação:

• Desativar integração: este botão desativa a integração na conta

• Editar integração: este botão inicia uma edição da integração

Para iniciar uma edição da integração, é preciso selecionar o botão “Editar integração”.

Uma vez que o botão seja acionado, será carregada a tela para o modo de edição da integração, então, após o carregamento a tela de configuração será exibida como no exemplo abaixo, contendo os botões de:

• Desativar integração: este botão desativa a integração na conta

• Descartar edições: este botão descarta as edições realizadas na configuração que não foram aplicadas ainda e encerra a edição da integração

• Aplicar edições: este botão aplica as edições realizadas na configuração da integração

Caso a edição tenha sido iniciada equivocadamente, ou sem querer ou simplesmente exista uma desistência da edição, a qualquer momento é possível acionar o botão “Descartar edições”, assim todas as edições serão ignoradas e excluídas e a integração seguirá operando normalmente com as informações da configuração anterior.

Durante a edição da integração é possível realizar qualquer configuração possível na configuração inicial da integração:

• Ativar ou desativar gatilhos de envio e/ou recebimento para qualquer entidade integrada.

• Incluir ou remover filtros de envio e/ou recebimento para qualquer entidade integrada.

• Incluir ou remover campos no mapeamento para qualquer entidade integrada.

Todas as alterações de configuração da integração possíveis de realização não impactam nos dados retroativos, isto significa que, por exemplo:

• Caso um gatilho de recebimento para criação de Propostas seja ativo e antes estava desatualizado, apenas as novas Propostas recebidas serão criadas e não serão criadas Propostas do passado.

• Caso um filtro de envio para criação de Cliente seja ativo e antes não existisse, apenas os novos cadastros criados no Ploomes seguirão essa regra do filtro criado.

• Caso um ou mais campos sejam incluídos no mapeamento de uma entidade, os cadastros existentes no Ploomes não serão preenchidos automaticamente. Apenas após as novas importações com o novo mapeamento ativo terão os cadastros recebidos com os dados novos do mapeamento.

• Caso um ou mais campos sejam removidos no mapeamento de uma entidade, os cadastros existentes no Ploomes não perderão seus dados preenchidos anteriormente. Apenas as novas importações com o novo mapeamento ativo terão os cadastros recebidos sem os dados dos campos removidos no novo mapeamento.

• Os cadastros que estiverem na fila de processamento da integração, não sofrem os impactos de edições da integração. Apenas os cadastros importados/exportados após a ativação da edição da integração seguirão os padrões na integração editada.

Ao editar a integração, é importante validar se algum campo mapeado do Ploomes ou do Sankhya, ou algum campo utilizado em algum filtro da integração, ou alguma opção pré-cadastrada utilizada em algum filtro da integração, ou alguma TOP do Sankhya ou Modelo de Documento do Ploomes tenham sido deletados ou editados. Caso ocorra alguma alteração desse tipo, a edição da integração não será aplicada e será necessário corrigir os erros identificados.

Para auxiliar na validação, é possível utilizar o botão de Sincronizar disponível em cada seção da configuração. Assim são trazidas os campos e opções pré-cadastradas existentes do Sankhya no momento da sincronização, evitando algum conflito por informação deletada ou alterada no Sankhya.

Ao acionar o botão de sincronizar, aparecerá uma mensagem para confirmação.

Após a sincronização que leva alguns segundos, será exibido um modal com o resultado da sincronização.

Caso todos os cadastros estejam sem erros é necessário salvar as edições realizadas em cada seção através do botão “Salvar edições”.

Após salvar as edições em todas as seções editadas, é possível aplicar as edições da integração. Importante: é necessário salvar as edições em todas as seções editadas, caso contrário não será possível aplicar a edição da configuração da integração.

Ao acionar o botão aplicar edições, será aberta uma nova janela com informações importantes sobre a alteração da integração e seu impacto. Nesta janela é possível cancelar a ação pelo botão “Cancelar” ou confirmar pelo botão “Aplicar edições”.

Será exibida uma caixa de seleção para Não atualizar as fórmulas dos campos ao aplicar edições.

• Caso a opção seja marcada, a integração não irá resetar as fórmulas de campos utilizados pela integração para o padrão da integração, preservando assim as eventuais edições e customizações realizadas.

• Caso a opção NÃO seja marcada, a integração irá resetar as fórmulas de campos utilizados pela integração para o padrão da integração, fazendo com que eventuais edições em fórmulas sejam descartadas.

Após aplicar as edições, então a integração seguirá a etapa de adequação dos cadastros no Ploomes:

• Compatibilização das opções pré-cadastradas entre campos: as opções pré-cadastradas existentes em campos do Ploomes são compatibilizadas com as opções pré-cadastradas dos respectivos campos mapeados do Sankhya.
  Isto é:

  • (1) opções pré-cadastradas que foram criadas no Sankhya após a última compatibilização da integração e que não existiam no Ploomes são criadas no Ploomes;

  • (2) opções pré-cadastradas que não existem mais no Sankhya e que ainda existem no Ploomes serão deletadas do Ploomes;

  • (3) opções pré-cadastradas que existem no Ploomes e que existem com o mesmo código e descrição no Sankhya serão mantidas sem alterações.

Após essas etapas serem processadas pela integração, a edição da integração estará aplicada e passará a valer para as novas edições e criações de cadastros no Ploomes e/ou Sankhya configuradas.

Com a integração ativa na conta após a aplicação de edição da configuração, o processo de configuração está concluído e a conta Ploomes pode ser utilizada integrada ao Sankhya normalmente.

---

---

3.2.2 Desativando a integração

Na tela de configuração da integração é possível acionar o botão de desativar a integração.

---

Observação importante sobre a desativação da integração

• Essa ação é extremamente arriscada e se acionada é irreversível.

---

A desativação da integração significa que uma conta Ploomes não estará mais integrada ao Sankhya e não fará exportações, importações nem consultas em tempo real ao Sankhya. Os cadastros existentes no Ploomes e no Sankhya se manterão normalmente com suas informações, no entanto a vinculação pela integração não existirá mais.

Ao acionar o botão de “Desativar a integração na tela de configuração, será exibida ainda uma nova janela para confirmação da ação.

Portanto, uma vez que a desativação é iniciada, são executadas as seguintes ações:

• Os webhooks do Ploomes e rotinas de consulta do Sankhya são desativados e não é possível mais enviar ou receber criações ou edições de cadastros.

• Os cadastros criados no Ploomes continuam existindo e com as informações que possuíam, seja em campos nativos, dinâmicos ou dinâmicos criados pela integração.

• Os campos criados com fórmulas para consultas em tempo real ao Sankhya continuam existindo com as fórmulas, mas as consultas não funcionam mais.

• Os ícones que indicam quais campos foram utilizados no mapeamento da integração deixam de aparecer.

• Os módulos de status da integração deixam de existir.

• Os registros de integração são apagados e as telas para acessá-los deixam de aparecer.

3.2.3 Reativando a integração

A reativação é o processo de ativação da integração numa conta Ploomes que já esteve integrada anteriormente.

Após desativar a integração, é possível sim ativar novamente a integração, no entanto, todo o processo de habilitação da integração, configuração da integração e carga inicial de dados será necessário.

Na habilitação da integração, na tela de inserção e validação do Token, é exibida uma opção de flag “Reutilizar última configuração ativa”. Caso essa opção seja marcada, ao habilitar a integração, na tela de configuração serão carregadas as seções configuradas conforme a última versão da integração ativa na conta. Ou seja, os mapeamentos de campos, gatilhos de ação, filtros de recebimento e TOP’s configurados na última versão ativa da integração poderão ser reutilizados.

Se iniciar uma reativação reutilizando a última versão da configuração ativa, será possível reaproveitar os mapeamentos, filtros e gatilhos configurados. No entanto, caso essa opção não seja selecionada, é preciso estar ciente de alguns comportamentos do mapeamento.

Comportamentos de mapeamento na reativação sem utilizar a última configuração ativa

• A integração irá sugerir a criação de novos campos com o mesmo nome dos campos dos criados na ativação anterior.
  Por exemplo:

  • Na primeira ativação foi criado o campo “Cód. Parceiro (Sankhya)”.

  • Na segunda ativação será sugerido a criação de um novo campo “Cód. Parceiro (Sankhya)”. Ou seja, um novo campo com o mesmo nome mas que ainda são campos diferentes.

    • Se o campo da segunda ativação for mantido no mapeamento, ele será criado ao ativar a integração e apenas ele estará mapeado. Ou seja, o campo da primeira ativação não será mais utilizado pela integração.

• Para evitar que um novo campo de mesmo nome seja criado, é preciso substituir o campo sugerido pela integração pelo campo já existente no Ploomes.

• Os campos utilizados na primeira ativação (ou ativação anterior) não serão sugeridos automaticamente. O usuário deverá trocar os novos campos sugeridos por campos existentes um a um.

• Se os campos utilizados para pareamento forem substituídos por campos diferentes dos que foram preenchidos na primeira ativação, a reativação poderá duplicar cadastros criados na primeira ativação.
  Por exemplo:

  • Na primeira ativação utilizei o campo “Cód. Parceiro (Sankhya)” para receber o código dos Parceiros do Sankhya.

  • Na segunda ativação troquei esse campo por um campo novo e não preenchido “Código dos Parceiros”.

    • Ao receber um Parceiro Cliente PJ do Sankhya, ele vai tentar ser pareado com Empresa do Ploomes através do campo "Código dos Parceiros", que está vazio.

      • Se ele não tiver CNPJ ou também não encontrar nenhuma Empresa com o mesmo CNPJ, será criada uma nova Empresa no Ploomes, mesmo que alguma Empresa tivesse o respectivo código no campo “Cód. Parceiro (Sankhya)" utilizado no mapeamento da primeira ativação.

Realizando a habilitação da integração, configurando a integração e ativando novamente, após a conclusão da carga inicial o processo de reativação estará concluído.

Com a integração ativa na conta novamente, o processo de configuração está concluído e a conta Ploomes pode ser utilizada integrada ao Sankhya normalmente.

---

---

4 Ativação

4.1 Ativação

Após configurar toda a integração, é possível realizar a Ativação da Integração.

Ao ativar a integração, ocorrem alguns eventos de preparação e então inicia-se a carga inicial de dados para serem integrados.

Os eventos que ocorrem ao ativar a integração são:

• Os campos dinâmicos sugeridos e utilizados nos mapeamentos são criados.

• A carga inicial de cadastros Sankhya e Ploomes é executada.

• Os ícones que indicam os campos utilizados no mapeamento de cada entidade ficam disponíveis.

• Os modais de status de integração das entidades ficam disponíveis.

• As consultas em tempo real de informações da Sankhya ficam disponíveis.

• Os webhooks de envio de criações e edições do Ploomes são ativados, passando a ser possível enviar cadastros e edições de cadastros para o Sankhya.

• As rotinas periódicas (pooling) de recebimento de criações e edições do Sankhya são ativadas, passando a ser possível receber cadastros e edições de cadastros no Ploomes.

• A tela de Registros da Integração fica disponível.

O progresso de ativação da conta da integração é exibido na tela de configuração.

É exibida uma barra de progresso da evolução das etapas de ativação, sendo a carga inicial de dados a mais custosa em complexidade e tempo de processamento.

Em cada etapa, é exibida um breve resumo que é atualizado num intervalo de tempo, detalhando quantos itens do Sankhya já foram salvos na fila ou quantos itens já foram processados.

A barra de progresso exibe um percentual que é simbólico e determina o avanço pelas etapas executadas, no entanto, as últimas etapas de carga de dados podem levar um tempo maior para conclusão, portanto é possível que o percentual pareça estagnado, no entanto os cadastros estão sendo processados para que a etapa seja finalizada.

Para que a integração esteja ativa e liberada para o uso, é necessário que a carga inicial esteja completamente concluída.

4.2 Carga inicial de dados

A carga inicial é uma etapa crucial para que a integração seja bem sucedida, portanto, antes de realizar a ativação é extremamente necessário validar toda a configuração da conta, em especial as vias de integração, filtros de recebimento e mapeamento de campos.

A carga inicial é realizada em 4 etapas:

1. Importação do Sankhya para o Ploomes de todos os cadastros do Sankhya que atendam às condições de recebimento configuradas (gatilhos e filtros) e aplicando as regras de pareamento para a importação em cada entidade.
   Nota sobre pareamentos:

   • Os cadastros recebidos que NÃO forem pareados darão origem a novos cadastros no Ploomes.

   • Os cadastros recebidos que forem pareados irão atualizar os cadastros existentes no Ploomes.

2. Exportar do Ploomes para o Sankhya os dados dos campos mapeados dos cadastros pareados do Ploomes que não foram atualizados no recebimento do cadastro do Sankhya.
   Exemplo:

   • Recebe um Parceiro que atualiza a Cidade e Endereço de uma Empresa com a qual foi pareado no Ploomes e, essa mesma Empresa, em seguida, exporta para o Sankhya seu e-mail, que só estava preenchido no Ploomes.

3. Exportar do Ploomes para o Sankhya todos os cadastros do Ploomes que não foram pareados ou criados a partir de cadastros importados do Sankhya e que atendam às condições de envio configuradas (gatilhos e filtros) e aplicando as regras de pareamento para a exportação em cada entidade.
   Nota sobre pareamentos:

   • Os cadastros enviados que NÃO forem pareados darão origem a novos cadastros no Sankhya.

   • Os cadastros enviados que forem pareados irão atualizar os cadastros existentes no Sankhya.

4. Importar do Sankhya para o Ploomes as atualizações de campos mapeados dos cadastros pareados do Sankhya que não foram atualizados no envio do cadastro do Ploomes.
   Exemplo:

   • Envia uma Pessoa que atualiza o telefone e e-mail de um Parceiro com o qual foi pareado no Sankhya e, desse mesmo Parceiro, em seguida, recebe no Ploomes uma atualização de cidade que só estava preenchido pelo Sankhya.

---

---

Após a conclusão da carga inicial, é possível utilizar a conta Ploomes integrada ao Sankhya normalmente.

A tela de configuração da integração passa a exibir para consulta as informações configuradas em cada seção e passam a estar disponíveis os botões de Desativação e Edição.

4.3 Modal de Status da Integração

Após a integração ser ativa na conta, é possível visualizar no menu superior o ícone com a logotipo da Sankhya, indicando que a conta Ploomes tem integração Sankhya ativa.

Ao clicar sobre o ícone, o usuário é redirecionado para a tela de consulta de Registros da Integração com o filtro pré-selecionado de usuário criador da ação. Dessa forma, será possível visualizar todas as edições realizadas pelo usuário em questão que geraram registros de integração.

Todas as entidades integráveis do Ploomes possuem um botão indicador de Status em sua tela de visualização.

Esse botão indica se o cadastro específico está integrado ou não. Ao clicar sobre o botão são exibidos detalhes sobre a integração do cadastro.

Quando o cadastro está integrado o modal de detalhamento exibe as seguintes informações:

• Campos mapeados para a entidade integrada.

• Campos chaves e seus respectivos valores do pareamento do cadastro.

• Gatilhos configurados para envio dos cadastros (se aplicável).

• Gatilhos configurados para recebimento dos cadastros.

Quando o cadastro NÃO está integrado não são exibidas nenhuma informação no modal de detalhamento.

Em todas as telas de cadastros existe a identificação com o ícone do Sankhya ao lado da descrição do campo para evidenciar um campo que é utilizado no mapeamento da integração para a entidade integrada.

Os campos que possuírem o ícone Sankhya ao seu lado direito são utilizados no mapeamento da integração e os que não apresentam o ícone Sankhya são campos do Ploomes que não são utilizados no mapeamento da integração.

A integração não realiza nenhuma alteração visual no layout do Sankhya para identificação dos registros integrados com o Ploomes. Esses modais de identificação de cadastros integrados existem somente no Ploomes.

---

5 Importação

5.1 Como funcionam Criação e Edição no Sankhya

Criação

Ao criar um novo cadastro no Sankhya em uma entidade configurada na integração, é registrado no banco de dados Sankhya a data da última modificação desse cadastro.

A transferência de dados do Sankhya para o Ploomes acontece de forma passiva para o Sankhya. Pois os dados são buscados pelo Ploomes através de um Pooling. O pooling funciona como um processo de varredura no Sankhya, verificando a data da última modificação dos cadastros no Sankhya, trazendo então os dados que foram modificados nos últimos 5 minutos.

O intervalo de 5 minutos do Pooling é o intervalo de verificação no Sankhya e não necessariamente o tempo necessário para uma atualização ser importada após alteração no Sankhya. Não há um tempo mínimo garantido para a integração. Pode ocorrer de os registros serem importados num intervalo menor ou maior do que os 5 minutos, dependendo sempre da disponibilidade do Sankhya e do volume de dados trazidos para a fila.

Esses dados de novas criações buscados, uma vez que atenderam aos filtros de recebimento, são salvos em uma fila de importação, e em seguida são processados e salvos no Ploomes.

Edição

Ao editar um cadastro no Sankhya em uma entidade configurada na integração, se o cadastro editado estiver integrado (ou seja, já foi processado pela integração anteriormente e está vinculado no Sankhya e no Ploomes), as edições realizadas serão capturadas pelo Pooling da integração, levando esses dados para o Ploomes.

O intervalo de 5 minutos do Pooling é o intervalo de verificação no Sankhya e não necessariamente o tempo necessário para uma atualização ser importada após alteração no Sankhya. Não há um tempo mínimo garantido para a integração. Pode ocorrer de registros serem importados num intervalo menor ou maior do que os 5 minutos, dependendo sempre da disponibilidade do Sankhya e do volume de dados trazidos para a fila.

Esses dados do cadastro editado precisam atender aos filtros de recebimento e via de integração configurados para que sejam de fato capturados pelo Pooling e enviados ao Ploomes.

Esses dados capturados, uma vez que atenderam aos filtros de recebimento, são salvos em uma fila de importação, e em seguida são processados e salvam a edição.

5.2 Gatilhos

Os “gatilhos da integração” definem quando um cadastro ou edição de cadastro são enviados/recebidos entre Ploomes e Sankhya para cada par de entidade integrada (ex: Empresa x Parceiro PJ).

Em qualquer um dos casos (Edição ou Criação), o cadastro passará a estar integrado e os gatilhos de envio ou recebimento de edições passarão a ser aplicáveis a esse cadastro.

Comportamento dos gatilhos:

• Só pode ser selecionado um gatilho de recebimento de criação/edição de cadastro por vez;

• São aplicados tanto na carga inicial quanto nas criações após a ativação da integração;

• Funcionam através de pooling - rotina periódica de 5 em 5 minutos que identifica a existência de novos cadastros ou cadastros existentes editados - que captura as informações atualizadas do Sankhya que atendam as condições de recebimento e eventuais filtros criados.

5.3 Filtros de recebimento

Os filtros de recebimento (ou importação) da integração são regras configuradas na integração que determinam quais informações devem ser recebidas do Sankhya no Ploomes.

• Comportamento geral dos filtros

  • Os filtros de recebimento de cadastros definidos são aplicados tanto na carga inicial da integração quanto durante o uso da integração;

  • Os recebimentos de cadastros que forem barrados pelo filtro não chegarão a ser exibidos na tela de logs, pois nem chegam para a fila da integração, já são barrados na origem;

  • Os filtros de recebimento também afetam os cadastros já integrados, ou seja, afetam o recebimento de edições. Portanto, um cadastro uma vez integrado, também pode ser barrado pelo filtro caso um de seus campos seja alterado de maneira que não atenda a um critério de filtro.

• Possibilidades de filtro de recebimento de cadastro

  • Filtro de recebimento de Parceiro Cliente PJ, Parceiro Cliente PF e Contato de Cliente para integração com Empresa ou Pessoa:

    • Filtro customizável através de campos nativos ou dinâmicos de Parceiro e Contato de Cliente, respectivamente;

    • Sem possibilidade de fieldpath (ou uso de campos de entidades relacionadas à empresa) no filtro;

    • Permite a combinação de regras de E e OU.

  • Filtro de recebimento de Produto/Serviço e Grupo de Produto/Serviço para integração com Produto e Grupo de Produto:

    • Filtro customizável através de campos nativos ou dinâmicos de Produto e Serviço;

    • Sem possibilidade de fieldpath (ou uso de campos de entidades relacionadas à produtos - ex.: estoque) no filtro;

    • Permite a combinação dessas duas regras com E e OU.

  • Filtro de recebimento de Vendedor para integração com Usuário:

    • Filtro customizável através de campos nativos ou dinâmicos de Vendedor;

    • Sem possibilidade de fieldpath (ou uso de campos de entidades relacionadas ao usuário) no filtro;

    • Permite a combinação dessas duas regras com E e OU.

  • Filtro de recebimento de Orçamento, Item do Orçamento, Pedido de Venda, Item do Pedido de Venda e Nota de Venda para integração com Proposta, Produto da Proposta, Venda e Produto da Venda e Venda respectivamente:

    • Filtro customizável através de campos nativos ou dinâmicos de Orçamento e Pedido de Venda;

    • Sem possibilidade de fieldpath (ou uso de campos de entidades relacionadas ao Orçamento ou Pedido de Venda) no filtro;

    • Permite a combinação dessas duas regras com E e OU.

5.4 Regras de Pareamento

As regras de pareamento são as condições definidas para a vinculação de cadastros do Sankhya com o Ploomes ou não.

Com base nessas regras de pareamento, ao receber um cadastro do Sankhya no Ploomes, é decidido se o cadastro recebido será vinculado a um cadastro existente no Ploomes ou se será criado um novo cadastro no Ploomes.

A tabela abaixo detalha resumidamente por quais campos chave os registros criados ou editados no Sankhya são identificados e pareados com os registros correspondentes no Ploomes durante o processo de importação.

5.5 Registros da Integração

Todos os eventos de integração (edições e criações de envio e de recebimento), que tenham atendido aos filtros de envio e recebimento, são registrados na tela Registros do Sankhya. Disponível na seção de Administração do Ploomes.

Ao acessar a tela de registros pelo menu de Administração, é possível consultar todos os eventos de importação da integração realizados na conta do cliente na integração vigente. Ou seja, se a integração for desativada e reativada, a tela de registros “limpa” todos os eventos armazenados, exibindo os eventos para consulta apenas da versão vigente da integração e suas edições.

Detalhes de como filtrar, onde acessar, quais dados estão disponíveis estão no artigo sobre a tela de registros.

---

6 Exportação

6.1 Como funcionam Criação e Edição no Ploomes

Criação

Ao criar um novo cadastro no Ploomes em uma entidade configurada na integração, é acionado o webhook do Ploomes. Esses webhooks do Ploomes são o gatilho de envio dos dados para o Sankhya.

A transferência de dados do Ploomes para o Sankhya acontece de forma ativa. Uma vez que a exportação depende exclusivamente da ação no Ploomes para que o webhook seja acionado e envie os dados para a integração.

Esses dados enviados, uma vez que atenderam aos filtros de envio, são salvos em uma fila de exportação, e em seguida são processados e salvos no Sankhya.

Edição

Ao editar um cadastro no Ploomes em uma entidade configurada na integração, é acionado o webhook do Ploomes. Se o cadastro editado estiver integrado (ou seja, já foi processado pela integração anteriormente e está vinculado no Sankhya e no Ploomes) e atender aos filtros de envio configurados, as edições realizadas serão enviadas para a fila da integração.

Uma vez que atenderam aos filtros de envio e foram salvos na fila de exportação, em seguida são processados e salvam a edição no Sankhya.

Ações de edição que não atendam ao filtro de envio serão bloqueados na exportação. Os dados dos webhooks dessas edições serão armazenados em uma tabela de exportações bloqueadas por até 30 dias e, durante esse intervalo, caso uma nova exportação atenda ao filtro de exportação os dados da edição anterior (ou das edições anteriores) serão exportados normalmente.

6.2 Gatilhos

Os “gatilhos da integração” definem quando um cadastro ou edição de cadastro são enviados/recebidos entre Ploomes e Sankhya para cada par de entidade integrada (ex: Empresa x Parceiro PJ).

Em qualquer um dos casos (Edição ou Criação), o cadastro passará a estar integrado e os gatilhos de envio ou recebimento de edições passarão a ser aplicáveis a esse cadastro.

Comportamento dos gatilhos:

• Só pode ser selecionado um gatilho de envio de criação/edição por vez;

• São aplicados tanto na carga inicial quanto nas criações após a ativação da integração;

• Funcionam através de webhooks de edição de cadastros, sendo que apenas os campos editados são enviados ao Sankhya e os mesmos precisam estar com a via de integração com sentido de envio para o Sankhya ativa.

6.3 Filtros de envio

Os filtros de envio (ou exportação) da integração são regras configuradas na integração que determinam quais informações devem ser enviadas para o Sankhya.

• Comportamento geral dos filtros

  • Os filtros de envio de cadastros definidos são aplicados tanto na carga inicial da integração quanto durante o uso da integração.

  • Os envios de cadastros que forem barrados pelo filtro não chegarão a ser exibidos na tela de logs, pois nem chegam para a fila da integração, já são barrados na origem.

  • Os filtros de envio também afetam os cadastros já integrados, ou seja, afetam o envio de edições. Portanto, um cadastro uma vez integrado, também pode ser barrado pelo filtro caso um de seus campos seja alterado de maneira que não atenda a um critério de filtro.

• Possibilidades de filtro de envio de cadastros

  • Filtro de envio Empresa ou Pessoa para integração com Parceiro Cliente PJ, Parceiro Cliente PF e Contato de Cliente:

    • Filtro customizável através de campos nativos ou dinâmicos de Empresa e Pessoa, respectivamente;

    • Sem possibilidade de fieldpath (ou uso de campos de entidades relacionadas à empresa) no filtro;

    • Permite a combinação de regras de E e OU.

  • Filtro de envio de Proposta ou Venda para integração com Orçamento e Pedido de Venda:

    • Filtro customizável através de campos nativos ou dinâmicos de proposta e venda, respectivamente;

    • Sem possibilidade de fieldpath (ou uso de campos de entidades relacionadas à empresa) no filtro

    • Sem possibilidade de fazer filtro com campos de produto da proposta ou produto da venda

    • Permite a combinação de regras de E e OU.

  • Filtros de envio de Usuário, Produto/Serviço, Grupo de Produto/Serviço e Nota de Venda NÃO EXISTEM, pois a integração não envia dados desses cadastros do Ploomes para o Sankhya.

6.4 Regras de Pareamento

As regras de pareamento são as condições definidas para a vinculação de cadastros do Sankhya com o Ploomes ou não.

Com base nessas regras de pareamento, ao enviar algum cadastro do Ploomes para o Sankhya, é decidido se o cadastro enviado será vinculado a um cadastro existente, se será criado um novo cadastro ou se a integração retornará erro.

A tabela abaixo detalha resumidamente por quais campos chave os registros criados ou editados no Ploomes são identificados e pareados com os registros correspondentes no Sankhya durante o processo de exportação.

6.5 Registros da Integração

Todos os eventos de integração (edições e criações de envio e de recebimento), que tenham atendido aos filtros de envio e recebimento, são registrados na tela Registros do Sankhya. Disponível na seção de Administração do Ploomes.

Portanto, usuários que não são administradores conseguem consultar apenas eventos de integração com origem no Ploomes (exportação) disparados pelo mesmo. Usuários não administradores não conseguem consultar todos os registros de integração da conta.

Detalhes de como filtrar, onde acessar, quais dados estão disponíveis estão no artigo sobre a tela de registros.

---

7 Consultas em tempo real

As consultas em tempo real são realizadas com finalidades específicas para entidades específicas. Essas consultas retornam a informação diretamente do Sankhya no momento em que são executadas.

7.1 Produto

7.1.1 Configuração das consultas

A configuração das consultas em tempo real para a entidade de Produtos é realizada em background pela integração.

É necessário apenas que o recebimento de Produtos / Serviços do Sankhya como Produtos no Ploomes esteja ativo.

7.1.2 Consultas realizadas

Consulta do estoque disponível

Para os Produtos que foram importados do Sankhya para o Ploomes e estão integrados é possível realizar a consulta de estoque disponível.

Essa consulta é executada na tela de cadastro de cada produto. Ao abrir o cadastro de um produto integrado, é necessário selecionar a unidade de medida e então é exibida uma tabela de estoque:

Nessa tabela, vão ser exibidos em linhas os estoques por:

• Empresa

• Local

• Controle

• E serão exibidos os totais das colunas de:

  • Estoque: quantidade total do Produto em estoque

  • Reservado: quantidade total reservada o Produto

  • Disponível: quantidade total de estoque do Produto que está disponível

• As quantidades exibidas são convertidas em função da unidade de medida selecionada. A conversão é feita pelo Sankhya, com base nos dados das entidades TGFEST (Estoque) e TGFVOA (Volume Alternativo) do Sankhya.
  ​
  Não é exibida a coluna de “Poder” na consulta de estoque. No entanto, caso o Sankhya esteja configurado para controlar estoques de em poder Próprio e de Terceiros, serão retornadas na consulta uma linha para cada Poder.

Abaixo estão descritos os comportamentos para:

• Proposta/Venda

• Produto da Proposta/Venda

Esses comportamentos são equivalentes entre as entidades de Proposta+Produto da Proposta e Venda+Produto da Venda, mas ainda assim no Ploomes, são distintas, portanto sua configuração, seus respectivos campos e parametrização no Ploomes são totalmente independentes.

7.2 Proposta ou Venda

7.2.1 Configuração das consultas

A configuração das consultas em tempo real para a entidade de Proposta/Venda é realizada em background pela integração e precisa ser habilitada na seção de configuração de consultas em tempo real.

Para essa consulta, é criado um campo no Ploomes que recebe esses dados das consultas possíveis para Propostas/Vendas. No entanto, é possível alterar o campo sugerido que receberá esses dados na tela de configuração da integração.

7.2.2 Consultas realizadas

Consulta de detalhes financeiros do Cliente da Proposta/Venda

Para os Parceiros do Sankhya que estão integrados ao Ploomes como um Cliente, é possível realizar a consulta de detalhes financeiros na tela de Propostas/Vendas.

Na tela de edição de Propostas/Vendas, é possível engatilhar a consulta de detalhes financeiro do Cliente ao selecionar um Cliente e uma TOP.

Exemplo de consulta aos detalhes financeiros do Cliente da Proposta após selecionar uma TOP.

Essa consulta retorna os dados em uma tabela resumo com os seguintes totais do Parceiro no Sankhya:

• Títulos a vencer

• Títulos em aberto

• Títulos em atraso

• Limite de crédito total

• Limite de crédito mensal

Os dados consultados são os mesmos exibidos na tela “Ficha de Parceiros” e são consultadas nos serviços de API FichaParceiroSP.getIndicadores e FichaParceiroSP.getFatiasPendenciasFInanceiras do módulo /mgecom/.

Para que essa consulta seja possível na tela de edição de Proposta/Venda, é necessário que o campo “Detalhes Financeiros (Sankhya)” - ou o campo utilizado no seu lugar na configuração - seja inserido no modelo de documento da Proposta/Venda. O campo pode ficar oculto que a consulta ainda irá funcionar.

Consulta de restrições de TOP

Para as TOP’s do Sankhya que estão configuradas no Ploomes para utilização nas Propostas/Vendas é possível realizar a consulta das restrições/exceções da TOP na tela de edição da Proposta/Venda.

Exemplo de consulta às restrições/exceções da TOP na tela de edição da Proposta após selecionar uma TOP.

Essa consulta retorna os dados em uma tabela resumo com os seguintes dados:

• Entidade: entidade que possui a restrição ou exceção com a TOP

• Restrição/Exceção: regra de negócio, se é uma exceção ou uma restrição

• Cadastros: código e descrição do cadastro relacionado a regra de negócio de restrição/exceção da TOP

No Sankhya, as restrições/exceções de TOP são uma regra de negócio importante e podem implicar no bloqueio da exportação de uma Proposta/Venda do Ploomes para o Sankhya caso alguma restrição/exceção não seja atendida.

As restrições podem ser de:

• Empresa

• Parceiro

• Tipo de Negociação

• Centro de Resultado

• Natureza

• TOP de Destino

• Produto/Grupo de Produto

• Usuário/Grupo de Usuário

• Perfil Principal

• Vendedor/Comprador

• Local

• Série

A consulta em tempo real às restrições/exceções de TOP não impede a seleção de opções restringidas pelo Ploomes, mas serve de referência para o preenchimento da Proposta/Venda.

Para que essa consulta seja possível na tela de edição de Proposta/Venda, é necessário que o campo “Detalhes de Restrições da TOP (Sankhya)” - ou o campo utilizado no seu lugar na configuração - seja inserido no modelo de documento da Proposta/Venda. O campo pode ficar oculto que a consulta ainda irá funcionar.

7.3 Produto da Proposta ou Produto da Venda

7.3.1 Configuração das consultas

A configuração das consultas em tempo real para a entidade de Produto da Proposta/Venda é realizada em background pela integração, com exceção das consultas de preço e imposto.

Para essas consultas configuradas em full background, são criados campos no Ploomes que recebem esses dados das consultas possíveis para Produto da Proposta/Venda. No entanto, é possível alterar o campo sugerido que receberá esses dados na tela de configuração da integração.

A principal configuração é realizada na criação de um campo do tipo desenvolvedor “Consulta única (Sankhya)”. Este campo possui a fórmula orquestradora das consultas de Produto da Proposta/Venda referente à valor unitário e impostos, determinando os gatilhos necessários para cada consulta possível.

A configuração das consultas de preço e impostos estão detalhadas neste artigo: Consultas em tempo real pela integração Sankhya.

7.3.2 Consultas realizadas

Consulta de unidades de medida

Para os Produtos da Proposta/Venda que são inseridos no formulário de CPQ é possível realizar uma consulta em tempo real ao Sankhya para exibir as unidades de medida do Produto.

Essa consulta retorna a unidade de medida padrão do produto e também as unidades de medida alternativas vinculadas ao Produto/Serviço do Sankhya que foi integrado ao Ploomes como Produto.

---

Engatilhamento da consulta

Para essa consulta ser engatilhada é necessário selecionar um Produto da Proposta/Venda*.

(*) Obrigatório

---

Essa consulta retorna uma lista de opções pré-cadastradas com as unidades de medida vinculadas ao Produto/Serviço no Sankhya.

Para que essa consulta seja possível no formulário de CPQ, é necessário que os campos “Consulta única (Sankhya)”, “Limpa opções (Sankhya)” e “Unidade de Medida (Sankhya)” - ou os campos utilizados no seu lugar na configuração - sejam inseridos no modelo de documento dentro do bloco de Produto da Proposta/Venda.

Os campo “Consulta única (Sankhya)” e “Limpa opções (Sankhya)” podem ficar ocultos que a consulta ainda irá funcionar.

É recomendado inserir o campo “Retorno consulta única (Sankhya)” de forma oculta para conseguir consultar o retorno recebido da consulta tem tempo real no Sankhya.

Consulta de controle

Para os Produtos da Proposta/Venda que são inseridos no formulário de CPQ é possível realizar uma consulta em tempo real ao Sankhya para exibir as opções de Controle do Produto.

Essa consulta retorna os Controles cadastrados para o Produto vinculados ao Produto/Serviço do Sankhya que foi integrado ao Ploomes como Produto.

---

Engatilhamento da consulta

Para essa consulta ser engatilha é necessário selecionar um Produto da Proposta/Venda* e opcionalmente uma Unidade de Medida.

(*) Obrigatório

---

Se a unidade de medida escolhida for a unidade de medida padrão, então serão exibidas as opções pré-cadastradas de todos os Controles possíveis para o Produto. Ou seja, possível também com todas as demais unidades de medida alternativas.

Se a unidade de medida escolhida for a unidade de medida alternativa, então serão exibidas as opções pré-cadastradas específicas para os Controles possíveis para o Produto com a unidade de medida selecionada.

Para que essa consulta seja possível no formulário de CPQ, é necessário que os campos “Consulta única (Sankhya)”, “Limpa opções (Sankhya)” e “Controle Produto (Sankhya)” - ou os campos utilizados no seu lugar na configuração - sejam inseridos no modelo de documento dentro do bloco de Produto da Proposta/Venda.

Os campos “Consulta única (Sankhya)” e “Limpa opções (Sankhya)” podem ficar ocultos que a consulta ainda irá funcionar.

É recomendado inserir o campo “Retorno consulta única (Sankhya)” de forma oculta para conseguir consultar o retorno recebido da consulta tem tempo real no Sankhya.

Consulta de estoque

Para os Produtos da Proposta/Venda que são inseridos no formulário de CPQ é possível realizar uma consulta em tempo real ao Sankhya para exibir uma tabela resumo com as informações de estoque disponível do Produto.

Essa consulta retorna uma tabela resumo com os dados de estoque do Produto/Serviço no Sankhya conforme os campos preenchidos no Ploomes.

---

Engatilhamento da consulta

Influenciam nessa consulta o preenchimento dos campos:

• Empresa

• Produto*

• Unidade de Medida*

• Controle

• Local
  ​ (*) Obrigatório

---

Nessa tabela, vão ser exibidos em linhas os estoques por:

• Empresa

• Local

• Controle

E serão exibidos os totais das colunas de:

• Estoque: quantidade total do Produto em estoque

• Reservado: quantidade total reservada o Produto

• Disponível: quantidade total de estoque do Produto que está disponível

As quantidades exibidas são convertidas em função da unidade de medida selecionada. A conversão é feita pelo Sankhya, com base nos dados das entidades TGFEST (Estoque) e TGFVOA (Volume Alternativo) do Sankhya.

O campo de consulta ao Sankhya e seu respectivo retorno estão na configuração da integração:

Para que essa consulta seja possível no formulário de CPQ, é necessário que o campo “Detalhes de Estoque (Sankhya)” - ou o campo utilizado no seu lugar na configuração - seja inserido no modelo de documento dentro do bloco de Produto da Proposta/Venda.

O campo “Detalhes de Estoque (Sankhya)” não pode ficar oculto.

Consulta de valor unitário

Para os Produtos da Proposta/Venda que são inseridos no formulário de CPQ é possível realizar uma consulta em tempo real ao Sankhya para obter o valor unitário do Produto.

Essa consulta retorna o valor unitário do Produto/Serviço do Sankhya integrado como Produto no Ploomes com base nos campos informados na Proposta/Venda (como Cliente, TOP, Tipo de Negociação, etc.) e no Produto da Proposta/Venda (Quantidade, Controle e Unidade de Medida) conforme a configuração de consulta de preço realizada.

Exemplo de consulta de Preço (Valor Unitário) em tempo real ao Sankhya de um Produto integrado na edição de uma Proposta após a alteração dos campos de Produto da Proposta que influenciam no preço.

---

Engatilhamento da consulta

Para essa consulta ser engatilhada, portanto, pode ser necessário informar:

• Na Proposta/Venda:

  • Empresa*

  • Cliente*

  • Tipo de Negociação*

  • Natureza*

  • Centro de Resultado*

  • Responsável*

  • TOP*

  • Outros campos eventualmente configurados.

• No Produto da Proposta/Venda:

  • Produto*

  • Unidade de medida*

  • Controle

  • Local*

  • Quantidade*

  • Outros campos eventualmente configurados.

(*) Obrigatório

---

A consulta retorna o valor unitário definido no Sankhya conforme preferência de regra de tabela de preço ou do preço dinâmico da conta Sankhya integrada.

Para que essa consulta seja possível no formulário de CPQ, é necessário que os campos “Consulta única (Sankhya)”, “Limpa opções (Sankhya)”e “Valor Unitário (Sankhya)” (ou o campo configurado para receber o valor unitário consultado) sejam inseridos dentro do bloco de Produto da Proposta/Venda, bem como todos os campos configurados para as consultas.

Os campos “Consulta única (Sankhya)” e “Limpa opções (Sankhya") podem ficar ocultos que a consulta ainda irá funcionar.

Consulta de impostos

Para os Produtos da Proposta/Venda que são inseridos no formulário de CPQ é possível realizar uma consulta em tempo real ao Sankhya para obter os dados de impostos do Produto.

Essa consulta retorna os valores de Valor Base, Alíquota e Valor do Imposto do Produto/Serviço do Sankhya integrado como Produto no Ploomes com base nos campos informados na Proposta/Venda e no Produto da Proposta/Venda.

---

*O NUNOTA Modelo utilizado é sempre o NUNOTA configurado para as consultas em tempo real de impostos.

Engatilhamento da consulta

Para essa consulta ser engatilhada, portanto, pode ser necessário informar os valores dos campos abaixo, conforme a configuração realizada:

• Na Proposta/Venda:

  • Nota Modelo*

  • Empresa*

  • Cliente*

  • TOP*

  • Finalidade da Operação

  • Valor do Frete

  • Valor do Seguro

  • Valor Outros

• No Produto da Proposta/Venda:

  • Produto*

  • Unidade de medida*

  • Quantidade*

  • Valor unitário sem desconto*

  • Percentual de desconto do Produto

(*) Obrigatório

---

O Sankhya pode ter diversos impostos configurados, portanto os retornos ou não dos impostos dependem diretamente da configuração dos parâmetros fiscais do Sankhya.

Os campos consultados no Sankhya e retornados no Ploomes são os seguintes:

• PIS (Base, Alíquota e Valor)

• COFINS (Base, Alíquota e Valor)

• ICMS (Base, Alíquota e Valor)

• IPI (Base, Alíquota e Valor)

• ST (Base, Alíquota e Valor)

• ISS (Base, Alíquota e Valor)

• IRPJ (Base, Alíquota e Valor)

• CPP (Base, Alíquota e Valor)

• INSS (Base, Alíquota e Valor)

• IRF (Base, Alíquota e Valor)

• CSSL (Base, Alíquota e Valor)

• Valor Total de Desoneração

• Valor FCP

• Valor DIFAL Remetente

• Valor DIFAL Destinatário

Para que essa consulta seja possível no formulário de CPQ, é necessário que os campos “Consulta única (Sankhya)” e “Limpa opções (Sankhya)” sejam inseridos dentro do bloco de Produto da Proposta/Venda. Também devem ser inseridos os respectivos campos dos impostos que forem configurados.

Por exemplo: caso seja necessário utilizar os dados de IPI, devem ser inseridos os campos configurados para receber o retorno da consulta desse imposto.

Os campos “Consulta única (Sankhya)” e “Limpa opções (Sankhya") podem ficar ocultos que a consulta ainda irá funcionar. É recomendado inserir o campo “Retorno consulta única (Sankhya)” de forma oculta para conseguir consultar o retorno recebido da consulta tem tempo real no Sankhya.

---

Pontos de atenção

• Os campos que recebem o retorno das consultas de impostos não são campos mapeados, portanto, tem o comportamento de campos não mapeados. Isto é, ao receber edições do Sankhya para o Ploomes, as informações podem ser apagadas.

  • No entanto, é possível mapear esses campos na seção da entidade de Produto da Proposta/Venda, de modo que ao receber importações do Sankhya para o Ploomes os dados venham preenchidos e sejam salvos no Ploomes.

• Preferências e regras configuradas no Sankhya podem impactar no cálculo de impostos via API. Para o cálculo da consulta de impostos retornar os dados de forma coerente com o Frontend Sankhya, o parâmetro das TOP’s para Cálculo de ICMS, IPI e ISS deve estar preenchido com a opção “Calcula e não digita”.

---

8 Ações em Tempo Real

É possível configurar e realizar as ações de Confirmar e/ou Faturar (apenas faturamento direto) CabecalhosNota do Sankhya através do Ploomes para os documentos que estejam integrados.

Essa funcionalidade está detalhada no artigo: Ações em tempo real pela integração Sankhya.

---

9 Recomendações

Abaixo, listamos recomendações técnicas para o bom funcionamento da integração:

• Configure o tempo mínimo de inatividade da sessão do usuário de integração para no mínimo 5 minutos, preferencialmente mais.

• Evite utilizar campos calculados ou virtuais no mapeamento.

• Mantenha o ERP Sankhya com estrutura de dados limpa e padronizada.

• Faça a ativação e configuração da integração com acompanhamento técnico da Ploomes.

• Garanta que o ambiente Sankhya permita conexões externas via API a partir do IP ou rede do Ploomes.

• Configure certificados SSL válidos para segurança da comunicação.

• Evite duplicidades de cadastros, principalmente Parceiros e Produtos.

• Verifique se o usuário de integração tem acesso total às tabelas integradas e as permissões necessárias para a integração.

• Recomendamos a utilização Sankhya hospedado em servidor em nuvem homologada pela Sankhya, pois será uma infraestrutura adequada e validada pela Sankhya, garantindo estabilidade e conectividade ideal para a comunicação via API.

• Não recomendamos a integração com Sankhya hospedado em servidor local, pois é mais propício aos problemas de conectividade via API, o que afeta diretamente a experiência e performance da integração. No entanto, este não é um impeditivo para realizar a integração.

  • Em caso de servidor local (ou nuvem própria), reforçamos o requisito de infraestrutura mínima recomendada pela Sankhya: https://ajuda.sankhya.com.br/hc/pt-br/articles/360045373654-Premissas-e-pré-requisitos-para-implantação.

  • A infraestrutura mínima não necessariamente é o ideal para todos os Sankhyas, pois existem dependências de performance no acesso aos dados via API como:

    • Quantidade de campos mapeados: quanto mais campos mapeados para a integração, maior será o tempo de processamento na consulta de dados ao Sankhya.

    • Quantidade de campos calculados: os campos calculados no Sankhya tornam o processo de consulta aos dados mais lento (pois requer o cálculo durante a consulta), portanto quanto mais campos calculados maior será o tempo de processamento.

    • Quantidade de ItemNota em CabecalhoNota: quanto mais itens existirem nos Orçamentos/Pedidos de Venda/Notas de Venda, maior será o tempo de processamento para a importação desses dados.

    • Internet disponível: a conectividade em servidores locais dependem muito mais da banda e internet disponível no servidor.

---

10 Limitações e observações importantes

Limitações Gerais

• A API do Sankhya possui uma limitação de 1000 requisições por minuto.

• O acesso ao Sankhya via API Gateway tem a limitação de até 2 minutos no tempo de processamento na infraestrutura do cliente Sankhya. Portanto, caso a infraestrutura do cliente demore mais do que 2 minutos para retornar alguma consulta, ocorrerá timeout - o que pode ser um impeditivo para a utilização da integração, conforme artigo Sankhya: https://developer.sankhya.com.br/reference/boas-práticas-para-integração.

• O Pooling (varredura por atualizações no Sankhya) é executado a cada 5 minutos; este é o intervalo de verificação, não o tempo para integrar cada item.

• Não há tempo máximo garantido para um item integrar, pois depende do volume de informações importadas.

• Eventos de integração negados por filtros não aparecem na tela de Registros da Integração.

• Ao desativar e reativar a integração, a tela de Registros da Integração "limpa" os eventos anteriores, exibindo apenas os da versão vigente.

• Usuários sem perfil de administrador só acessam os registros pelo ícone no menu superior direito e só visualizam registros de criações/edições feitas por eles no Ploomes.

• Não é possível importar campos com dados binários que contenham conteúdos como anexos, imagens etc.

Mapeamento de Campos

• Campos virtuais do Sankhya que não existem na entidade principal integrada não podem ser mapeados.

• Campos de mapeamento fixo não podem ter seu tipo de campo alterado no Ploomes.

• Existe um limite de criação de 40.000 opções pré-cadastradas em campos do Ploomes.

• Quanto mais campos forem adicionados no mapeamento, mais lenta será a velocidade de processamento de dados (importação e exportação). Isso também afeta o tempo da carga inicial.

• O mapeamento de campos calculados do Sankhya afeta bruscamente a velocidade de importação.

• Se um campo desejado não estiver mapeado e for incluído após a carga inicial, os dados desse campo não serão preenchidos automaticamente para os cadastros já integrados, apenas para novas importações/exportações.

• Se um campo mapeado (do Ploomes ou Sankhya) for deletado (especialmente durante a carga inicial), a carga inicial falhará e retornará erro.

• Alterações em nomes de campos, obrigatoriedades ou opções pré-cadastradas em campos mapeados com a integração ativa podem exigir nova compatibilização ou alteração do mapeamento.

• Ao editar a integração, se um campo mapeado, campo de filtro, opção pré-cadastrada em filtro, TOP ou Modelo de Documento for deletado ou editado, a edição da integração não será aplicada e exigirá correção.

• Apenas os campos abaixo são convertidos automaticamente como opções pré-cadastradas no Ploomes. Outros campos do Sankhya ausentes na lista abaixo serão importados apenas com sua chave externa (ID) em um campo de número inteiro.

  - Empresa (TGFCAB)

  - TOP (TGFCAB)

  - Tipo de Negociação (TGFCAB)

  - Natureza (TGFCAB)

  - Centro de Resultado (TGFCAB)

  - Status da Nota (TGFCAB)

  - Transportadoras (TGFCAB)

  - Local (TGFITE)

  - Controle (TGFITE)

  - Unidade de Medida (TGFITE)

  - Classificação ICMS (TGFPAR)

Habilitação e Carga Inicial

• A carga inicial não pode ser cancelada pelo usuário do Ploomes.

• Não é possível aplicar filtros durante o processo de carga inicial se ela não for interrompida por erro.

• Não é recomendado executar a carga inicial sem aplicar filtros de recebimento e sem conhecimento do volume de dados no Sankhya.

• Limitações no servidor Sankhya, erros na API ou timeout de requisições (acima de 120 segundos) podem paralisar a carga inicial.

• Se o Token de integração for inativado ou removido durante a carga inicial ou uso, nenhuma operação de integração será possível.

• Ao reativar a integração, todo o processo de carga inicial precisa ser feito novamente, mesmo para cadastros já existentes no Ploomes, e tende a ser mais demorado devido às tentativas de pareamento.

• Quanto mais cadastros existirem no Ploomes, maior será o tempo de processamento da carga inicial devido às tentativas de pareamento.

• Para ativar a integração nas entidades de Propostas e Vendas, é necessário contratar o módulo de CPQ.

Configuração e Edição

• Ações de alteração na configuração da integração podem causar impactos significativos e são irreversíveis.

• Alterações de configuração realizadas após a primeira ativação não impactam nos dados retroativos.

• Os cadastros que estiverem na fila de processamento da integração não sofrem os impactos de edições aplicadas; apenas os processados após a nova configuração estar vigente.

• Não é possível desativar a integração se estiver no modo de edição (Draft). É necessário descartar as edições primeiro.

• É necessário clicar em "Salvar edições" no final de cada seção editada antes de clicar em "Aplicar edições" para que as alterações sejam salvas e aplicadas. Caso contrário, o mapeamento pode não ficar salvo.

• Durante a aplicação de edição, a barra de porcentagem de processamento é simbólica e pode parecer travada; o processamento real deve ser verificado via network. Há uma proteção para não haver filas de processamento concomitantes.

Limitações por Entidade / Funcionalidade

• Parceiro (Cliente PJ e PF) / Empresa / Pessoa:

  • Se uma Empresa foi importada do Sankhya e o Parceiro PJ for apagado no Sankhya, o pareamento continua valendo.

  • Mesmo que o Parceiro mude seu status para Inativo, se já estiver integrado, continuará podendo enviar e receber atualizações.

  • Se existirem vários Parceiros PJ no Sankhya com o mesmo CNPJ, a Empresa no Ploomes será integrada com o Parceiro que tiver o menor código (CODPARC).

  • Campos de tabelas personalizadas não são integrados, a menos que sejam enviados na tabela TGFPAR.

  • O mapeamento de bairros, endereço e cidade é feito pelo nome, não pelos códigos (CODBAI, CODEND, CODCID). Ao enviar edições de um parceiro integrado, pode-se mudar o CODBAI, CODEND ou CODCID vinculado a ele no Sankhya se houver cadastros duplicados com o mesmo nome no Sankhya.

  • O CNPJ já estar cadastrado no Sankhya como Pessoa Física impede a criação de um novo Parceiro PJ.

  • Problemas com cadastro de endereço (Cidade, Bairro ou Endereço) no Sankhya podem causar falha na criação.

  • Se uma Empresa no Ploomes perder um campo obrigatório no Sankhya (ex: Nome ou Cidade), a edição poderá falhar.

  • Edições em campos não mapeados não geram atualização no Sankhya.

  • Se um cliente Pessoa (Parceiro PF) integrado no Sankhya for alterado para Pessoa Jurídica, criará um novo cliente Empresa no Ploomes com o mesmo código de Parceiro, pois o Ploomes não converte PF para PJ. Os cadastros de Pessoa Física "se tornam órfãos".

  • A edição de telefone do Parceiro no Sankhya tem o comportamento de adicionar mais um telefone no Ploomes em vez de alterar, devido à limitação do Sankhya que integra apenas a primeira posição de um tipo de telefone.

• Contato de Cliente:

  • Somente são integrados Contatos de Cliente de Parceiros Pessoa Jurídica. Eles precisam ter um Parceiro integrado.

  • No Sankhya, se um contato é contato de 2 parceiros, é necessário cadastrá-lo em cada parceiro.

  • A integração preenche somente o Contato da Venda ou da Proposta, não preenche o contato do Negócio.

• Produto / Serviço:

  • Não é possível exportar Produtos/Serviços do Ploomes para o Sankhya. A via de integração é somente Sankhya → Ploomes.

  • Produtos criados manualmente no Ploomes não são enviados ao Sankhya em vendas/propostas porque não estão integrados.

  • No primeiro recebimento, são recebidos somente Produtos/Serviços ativos no Sankhya. Após a integração, edições podem ser recebidas mesmo se o produto ficar inativo.

  • A deleção de um Produto/Serviço no Sankhya ou de um Produto no Ploomes não é refletida no outro sistema .

  • Produtos/Serviços não importados pela via principal (ex: por filtro) ainda podem ser importados se estiverem em um Orçamento, Pedido de Venda ou Nota de Venda importado. O grupo desse produto também é integrado.

  • Produtos/Serviços não possuem campo para informação de valor unitário na entidade; isso é definido na geração de documento.

  • A consulta em tempo real de Controle do Produto somente funciona se o Controle no Sankhya estiver cadastrado como "Lista" (TIPCONTEST = 'S'). A integração só olha informações de Controles de GET Produto ou GET Volume Alternativo, independente da configuração TIPCONTEST.

  • A consulta em tempo real de Estoque exige que o campo "Detalhes de Estoque (Sankhya)" (ou mapeado) não esteja oculto no modelo de documento.

  • Na visualização do estoque, podem aparecer Empresas/Locais repetidos, refletindo dados retornados pela consulta no Sankhya (ex: Poder Terceiros e Poder Próprio), mas não estão realmente duplicados; a coluna "Poder" não é exibida no Ploomes.

• Orçamento / Pedido de Venda / Nota de Venda:

  • Não é possível exportar Notas de Venda do Ploomes para o Sankhya.

  • Os campos mapeados para Pedidos de Venda são reutilizados para a importação de Notas de Venda.

  • As TOPs de Tipo de Movimento = "V" (Notas de Venda) só são exibidas como opção para configuração na seção de Notas de Venda.

  • Os filtros configurados nos modelos de documento do Ploomes (filtros de seção/blocos de produto da proposta) são ignorados na importação de Propostas/Vendas vindas do Sankhya. A integração divide em blocos padrão.

  • Para Propostas/Vendas de Parceiros Pessoa Física, não se deve adicionar o contato no campo "Contato" da proposta; o cliente Pessoa Física deve ser apenas o Cliente do Card.

  • Orçamentos/Pedidos de Venda de Contato de Cliente exigem que o Parceiro Pessoa Jurídica vinculado ao contato seja inserido no Negócio/Venda/Proposta para poder integrar.

  • Quando edições em campos de produto da Proposta/Venda são enviadas ao Sankhya, a API do Sankhya remove todos os produtos e tenta reinseri-los. Se ocorrer um erro durante a reinserção, os produtos podem ser removidos e não adicionados novamente, resultando em um documento sem produtos. Este é um comportamento de limitação da API do Sankhya.

  • As edições no Sankhya são capturadas pelo Pooling somente se o campo DTALTER for alterado. Edições feitas diretamente no banco de dados ou por fórmulas que não atualizem o DTALTER não serão enviadas para o Ploomes.

  • Quando edições vindas do Sankhya são recebidas, o preenchimento de campos de Produto da Proposta (ou Produto da Venda) que não estão mapeados na integração é removido. A integração recria os produtos preenchendo apenas os campos mapeados.

  • Edições feitas no Ploomes só entram na fila de envio se houver alterações em campos mapeados.

  • Se uma edição no Ploomes for barrada inicialmente por um filtro de envio, e o campo do filtro for editado para atender à condição, a edição original nos outros campos mapeados ficará armazenada em uma tabela de itens bloqueados na exportação por até 30 dias e podem ser enviados ao Sankhya normalmente após uma nova edição passar a atender o filtro. Após esse período serão descartados.

  • Vendas/Orçamentos só integram se o Cliente selecionado já estiver integrado ao Sankhya.

  • Duplicar uma proposta integrada no Ploomes sem remover o Nro. Único (Sankhya) impede a exportação do documento para o Sankhya.

  • Vendas e Propostas só vinculam a um Negócio já existente no Ploomes se o campo de Id de Negócio estiver mapeado e preenchido na CRIAÇÃO. O valor preenchido no campo ID do Negócio é considerado apenas na criação de importação; em edições, o valor vindo nesse campo não é usado.

  • Edições/alterações de Parceiros de Propostas/Negócios já existentes no Ploomes são refletidas no Ploomes.

  • Não é realizada confirmação nem faturamento automático de Orçamentos ou Pedidos de Venda no Sankhya pela integração, somente através de ações manuais.

• TOPs:

  • Uma TOP só pode ser utilizada em uma entidade escolhida (Proposta, Venda ou Nota Fiscal); não é possível selecionar a mesma TOP para múltiplos tipos de documento.

  • Na seleção de TOPs para Pedido de Venda e Orçamentos, são exibidas todas as TOPs ativas, exceto as de Tipo de Movimento "V".

Consultas em Tempo Real

• As informações consultadas em tempo real não estão armazenadas no Ploomes. Portanto, não é possível utilizar esses dados para automações, formulários ou outras ações que requeiram um dado armazenado no banco de dados do Ploomes.

• O campo de consulta ao Controle do Produto só exibe opções se o Controle no Sankhya estiver cadastrado como "Lista" (TIPCONTEST = 'S'), apesar da integração olhar para outros locais na API.

• Os campos de consulta de impostos da integração no Ploomes NÃO NECESSARIAMENTE SÃO CAMPOS MAPEADOS. Eles existem para receber o retorno da consulta feita no Sankhya.

• Os valores dos campos de consulta (Detalhes Financeiros, Restrições de TOP, Detalhes de Estoque, Valor Unitário, Produto Integrado, Impostos) têm seu preenchimento removido em edições recebidas pelo Sankhya. Isso ocorre porque esses campos não existem no Sankhya e não são trazidos na importação; a integração recria os produtos preenchendo apenas os campos mapeados.

• Se a configuração da TOP no Sankhya estiver marcada como "Calcula e Digita” em “Cálculo de ICMS, IPI e ISS”, não retornará corretamente os impostos na integração Sankhya nem por API. Precisa ser trocado para "Calcula e Não Digita”.

---

11 FAQ - Perguntas Frequentes

1. A integração entre o Ploomes e o Sankhya é bidirecional?

   • Sim, a integração é bidirecional, permitindo a importação e exportação de dados entre os sistemas, com exceção dos cadastros de Produtos, Grupos de Produtos e Vendedores, que possuem integração unidirecional (Sankhya > Ploomes).

2. Quais dados podem ser importados do Sankhya para o Ploomes?

   • Dados como parceiros clientes, produtos/serviços, grupos de produtos/serviços, vendedores, orçamentos, pedidos de venda, e notas de venda podem ser importados.

3. Posso exportar Notas de Venda do Ploomes para o Sankhya?

   • Não, a exportação de Notas de Venda do Ploomes para o Sankhya não é suportada.

4. Como são realizadas as consultas em tempo real durante a criação de documentos?

   • Durante a criação de propostas ou vendas no Ploomes, o sistema realiza consultas em tempo real ao Sankhya para obter preço, estoque, e impostos dos produtos, limites de crédito de Parceiros e restrições de TOP.

5. O que acontece se eu cancelar ou excluir um documento no Sankhya?

   • O cancelamento de documentos no Sankhya pode ser sincronizado como uma deleção no Ploomes, desde que o gatilho de importação de cancelamento esteja habilitado. O mesmo comportamento ocorre para deleções de documentos, que dependem de gatilho específico estar ativo.

6. Posso configurar quais dados serão importados ou exportados?

   • Sim, a configuração de filtros e mapeamentos permite personalizar quais dados serão importados ou exportados entre os sistemas. Campos virtuais do Sankhya não podem ser utilizados no mapeamento.

7. A integração pode ser utilizada para importar dados históricos de documentos antigos no Sankhya?

   • Sim, a integração importa os dados históricos do Sankhya para o Ploomes durante a carga inicial na ativação da integração somente. Após a ativação, a integração somente trabalha com dados criados ou editados desde então.

8. Como posso garantir que o estoque no Ploomes esteja sempre atualizado?

   • A atualização de estoque deve ser gerida no Sankhya. A integração realiza consultas em tempo real ao ERP para refletir o estoque disponível no Ploomes.

9. É possível editar documentos no Sankhya após a exportação para o Ploomes?

   • Sim, mas é importante que as edições sejam feitas com cautela, pois a sincronização de alterações pode gerar inconsistências, especialmente se ocorrerem edições simultâneas.

10. Quais limitações existem para o mapeamento de campos?

    • Campos virtuais no Sankhya não podem ser mapeados. Apenas campos existentes fisicamente nas entidades integradas e em tabelas complementares (com relacionamento 1-1) podem ser sincronizados.

11. O que devo fazer se os dados não estiverem sendo importados corretamente?

    • Verifique se os campos obrigatórios estão preenchidos corretamente no Sankhya e se os gatilhos e filtros da integração estão configurados corretamente.

12. Há algum limite para o número de opções pré-cadastradas nos campos?

    • Sim, o Ploomes suporta até 40.000 opções pré-cadastradas em campos do tipo lista. Exceder esse limite pode causar falhas. Não há atualização periódica automática das opções pré-cadastradas importadas do Ploomes para o Sankhya.

13. A integração oferece suporte a customizações avançadas realizadas no Sankhya?

    • Não, a integração suporta apenas campos e dados que estão presentes nas entidades principais do Sankhya integradas. Customizações profundas podem exigir desenvolvimento adicional.

14. Quais problemas podem ocorrer se houver falha na sincronização de dados?

    • A falha pode ocorrer devido a edições simultâneas nos documentos, campo obrigatório não preenchido ou problemas de conectividade. É importante monitorar a API e garantir a integridade dos dados antes da sincronização.

15. É possível realizar a integração com Views criadas no Sankhya ?

    • Não. Não é possível realizar integração com Views pela integração. Caso seja necessário deverá ser feito um desenvolvimento adicional personalizado.