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.

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.

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

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.

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.

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.

# Observações importantes sobre a autenticação da integração no Sankhya

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.

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:

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.

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.

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.

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

As possibilidades são:

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.

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.

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:

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:

Exemplo de aplicação da regra

Supondo a aplicação da regra considerando a notação de opções assim indicadas ([NOME DA OPÇÃO], [chave da opção]):

Então o campo no Ploomes com a compatibilização pela regra acima descrita terá as seguintes ações:

Resultando nas seguintes opções pré-cadastradas no campo do Ploomes:

# Observações importantes sobre limite de opções pré-cadastradas

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

# Observações importantes sobre mapeamentos

Esse conjunto de padrões de configuração da integração determinam o comportamento da integração na conta Ploomes.

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.

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:

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.

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.

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:

Para as consultas na tela de geração de Propostas, são configurados os seguintes campos de consulta a dados 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:

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

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:

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:

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

# Observações importantes sobre consultas em tempo real

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:

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:

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:

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:

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:

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

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

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.

# Observações importantes sobre a edição da 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

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:

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.

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.

Observações importantes sobre a reativaçã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:

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.

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:

# Observações importantes sobre a carga inicial

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.

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:

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.

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.

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.

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:

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.

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.

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.

Os registros estão divididos em duas abas: Exportações e Importações.

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.

O acesso total aos eventos de integração pelo menu de administração está disponível somente para os usuários administradores da conta Ploomes.

Para os demais usuários é possível também consultar a tela de registros do Sankhya através do botão com Ícone do Sankhya, que está acessível na parte superior à direita em qualquer tela do Ploomes.

No entanto, ao abrir a tela de registro da integração por este botão, serão exibidos somente os eventos de exportação que foram originados no Ploomes e disparados a partir do usuário que estiver logado acessando a tela.

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.

Para realizar a consulta dos registros é obrigatório informar ao menos a entidade Sankhya integrada e o intervalo de data.

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.

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.

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:

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.

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.

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.

Os registros estão divididos em duas abas: Exportações e Importações.

Ao acessar a tela de registros pelo menu de Administração, é possível consultar todos os eventos de exportação da integração realizados na conta do cliente na integração vigente. Ou seja, a cada vez que a integração é editada, ou desativada e reativada, a tela de registros “limpa” todos os eventos de exportação armazenados, exibindo os eventos para consulta apenas da versão vigente da integração.

O acesso total aos eventos de integração pelo menu de administração está disponível somente para os usuários administradores da conta Ploomes.

Para os demais usuários é possível também consultar a tela de registros do Sankhya através do botão com Ícone do Sankhya, que está acessível na parte superior à direita em qualquer tela do Ploomes.

No entanto, ao abrir a tela de registro da integração por este botão, serão exibidos somente os eventos de exportação que foram originados no Ploomes e disparados a partir do usuário que estiver logado acessando a tela.

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.

Para realizar a consulta dos registros é obrigatório informar ao menos a entidade Sankhya integrada e o intervalo de data.

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.

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.

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:

Abaixo estão descritos os comportamentos para:

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.

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.

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:

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.

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:

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:

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.

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.

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.

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.

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:

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

E serão exibidos os totais das colunas de:

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.

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:

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

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:

(*) 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:

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

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