Manual de Integração: Parametrização Fiscal
Manual contendo as últimas atualizações efetuadas em 29/04/2021.

Introdução
Este manual destina-se às equipes de desenvolvimento que pretendam integrar com a nossa solução de Parametrização Fiscal, uma solução preventiva (“para o presente e futuro”) em que a Systax entrega ao cliente e monitora as regras tributárias aplicáveis a ele. Isso é possível porque a Systax criou e mantém a maior base de regras de tributação do Brasil, aplicáveis em operações envolvendo mercadorias, em qualquer segmento e em qualquer UF, incluindo operações interestaduais. Tratamos a tributação federal (IPI, PIS e COFINS) e estadual (ICMS, incluindo ST, Antecipação e Partilha do ICMS, nas 27 UF). Nenhuma outra empresa no Brasil consegue atender todas as 27 UF e todos os segmentos.

Principais conceitos envolvidos nas regras da Systax
Entenda alguns conceitos envolvidos na produção do conteúdo da Systax (as regras): 

 

 Uma “regra fiscal” deve trazer informações suficientes para o usuário conseguir calcular os tributos e emitir uma NF-e (cenários de saída), ou conferir a tributação de uma NF-e de seu fornecedor (cenários de Entradas); 

 Em cenários de Entrada (quando o nosso cliente é o destinatário na operação), a regra da Systax também deve trazer informações para que o usuário saiba como escriturar a Entrada (códigos e cálculo dos créditos); 

 Um “Cenário de Operação” é a combinação de algumas variáveis, sendo as principais: • natureza de operação: para o remetente. Ex: venda, transferência, etc. • destinação: objetivo para o destinatário, em operações de entrada. Ex: para revenda, para ativo, para uso e consumo, etc. • UF de origem • UF de destino • Perfil do remetente: Ex: indústria; Varejista do Simples Nacional; Indústria com o Regime especial XPTO... (detalhe: os “perfis” podem conter listas e não apenas uma única característica). • Perfil do destinatário Ex: varejista; Consumidor final não-contribuinte, etc. • Outros atributos também podem fazer parte do cenário (CNAE, Municípios, etc.) 

 Uma regra é identificada pelo cenário e pela mercadoria a que pertence. A “chave” de identificação da mercadoria é o “código_interno” (código adotado pelo cliente) + “origem_da_mercadoria” (aquela tabela de 0 a 8, adotada na NF-e e SPED: nacional, importado...). Ou seja, para a Systax é possível termos vários registros para o mesmo código de mercadoria, desde que tenham origens diferentes (a origem faz parte da chave do registro); 

 As mercadorias são cadastradas na Systax com 6 campos de informações: • Código de produto -> (Texto 60 caracteres) obrigatório; • Origem Produto -> (Numérico) obrigatório, conforme tabela oficial de Origem Produto (zero a 8) • NCM -> (8 dígitos - mínimo 2 dígitos) obrigatório; • Ex TIPI -> (Numérico) - "Ex" utilizado para a tabela de Incidência do IPI (TIPI); • CEAN - Código de barras -> (Numérico - máximo 14 dígitos); não é obrigatório, pois pode não existir; mas se existir, é muito importante! • Descrição -> (Texto 120 caracteres) obrigatório. 

 As regras contêm blocos de informação, organizando os dados por tributo. Exemplo: ICMS próprio, Crédito de ICMS, ICMS/ST, Partilha do ICMS, IPI-Débito, IPI-Crédito, etc. 

 Geramos uma regra para cada item de mercadoria, em cada cenário de operação que a empresa precisar (num raciocínio simples: 500 itens e 3 cenários de operação vão gerar 1.500 regras). Há recursos para que o usuário possa especificar restrições para gerarmos regras apenas para alguns produtos em cada cenário (usando os “grupos de produtos”); 

 AGRUPAMENTO - dependendo do segmento e características do cliente, não é necessário gerar regras individualizadas por mercadorias, podendo-se trabalhar com grupos ou famílias. Exemplos: a. Supermercados e Farmácias possuem tantas exceções (como o “preço máximo ao consumidor” de cada item da farmácia), que só é seguro gerar regras individualizadas para cada mercadoria; b. Livrarias, lojas de confecções, calçados, etc – podem trabalhar muito bem se gerarmos regras por família ou agrupamentos de mercadorias que tem os mesmos tratamentos tributários – o cliente definirá se ele mesmo vai administrar os grupos ou se a Systax fará isso. c. Alguns segmentos de indústrias podem operar confortavelmente com regras por NCM (quando a legislação não estabelece exceções de tributação dentro de uma mesma NCM). 

 A base produzida pela Systax organiza as regras na seguinte ordem de entrega: Cenário de Operação 1 Produto 1 Produto 2 ... Cenário de Operação 2 Produto 1 Produto 2 ... Cenário de Operação N Produto 1 Produto 2 ... 

 Se contratado monitoramento, é mais eficiente o cliente se atualizar buscando apenas o que mudou desde a última atualização (processo incremental), mas sempre que quiser poderá fazer uma “carga completa” novamente.

Fluxo de informações
Para viabilizar um processo eficiente de atualização do conteúdo no cliente, é preciso definir pelo menos dois fluxos de informações: 

 

 Do cliente para a Systax: a. Toda mercadoria nova ou alterada deve ser encaminhada para inclusão na base de monitoramento. Esse envio pode ser automatizado (pela integração) ou manual (por digitação ou importação de listas). b. Novas operações (com UFs diferentes, p.ex.) precisam ser alinhadas com a Systax para inclusão de novos cenários na base de regras. A inclusão de cenários pode ser automatizada (pela integração) ou por demanda ao atendimento da Systax (o que é mais comum, já que alterações de operações normalmente não são frequentes). 

 Da Systax para o Cliente: a. Toda regra que sofra alteração é entregue para o cliente. Processos recorrentes (normalmente diários) fazem a leitura das regras novas ou alteradas. b. Pode-se estabelecer uma rotina automática, diária (ou com a periodicidade que o cliente preferir) para busca das atualizações no sistema da Systax. E podem ser executadas cargas eventuais (urgentes) se surgir necessidade. 

 

 Fluxos Opcionais: 

 

 Pode-se administrar também a relação “N-N” entre mercadorias e cenários, com os “ Grupos de Produtos ”. Existem métodos específicos para isso. 

 Para integrações em parceiros de ERP, pode ser útil combinar a automação do cadastramento de “ clientes novos ”, ativando novas bases de regras; 

 Clientes com necessidades mais complexas de  gestão de cadastros  (workflow de itens novos, p.ex.) podem ter integração para tratamento de dúvidas técnicas e etapas de “classificação fiscal”. 

 Produção de  regras complementares “on demand”  - esse serviço poderá ser aplicado em clientes que tenham operações complexas e muito dinâmicas, quando não conseguem definir com antecedência as mercadorias e cenários que precisarão processar. Essa solução permite produzir e entrega uma regra de tributação “online”, em requisição síncrona, podendo ser aplicada como contingência eventual à falta de regras. Se precisar desse recurso, solicite mais informações à Systax 

 

 Modelos de Integração disponíveis  

 A Systax dispõe de algumas opções para integração. O quadro abaixo resume as principais características, que serão detalhadas mais abaixo: 

 

 

 

 

 # 

 

 

 Forma de Integração 

 

 

 Características 

 

 

 

 

 Comunicação 

 

 

 Apresentação de dados ao usuário 

 

 

 Vantagens 

 

 

 Desvantagens 

 

 

 Esforço Técnico (desenvolvimento) 

 

 

 custos adicionais 

 

 

 

 

 1 

 

 

 Webservice 

 

 

 Soap/XML 

 

 

 a ser construída do lado do cliente 

 

 

 integração direta entre ERP e Systax 

 

 

 esforço para criar as telas de apresentação ao usuário 

 

 

 consumo do webservice; telas de apresentação ao usuário 

 

 

 nenhum 

 

 

 

 

 2 

 

 

 Cockpit em nuvem 

 

 

 conexão direta ao banco de dados 

 

 

 pelas telas do cockpit, ou, opcionalmente, telas criadas pelo parceiro. 

 

 

 interfaces visuais prontas para gerenciamento do conteúdo (consultas, aprovações, etc.) 

 

 

   

 

 

 consumo de regras com query em conexão direta no banco de dados 

 

 

 adicionado à mensalidade, conforme negociação 

 

 

 

 

 3 

 

 

 Cockpit local 

 

 

 conexão direta ao banco de dados 

 

 

 pelas telas do cockpit, ou, opcionalmente, telas criadas pelo parceiro. 

 

 

 interfaces visuais prontas, facilidade para integração com aplicações internas 

 

 

 necessidade de disponibilizar infraestrutura e ainda assumir o esforço das atualizações periódicas de versões do Cockpit 

 

 

 consumo de regras com query em conexão direta no banco de dados 

 

 

 nenhum 

 

 

 

 

 4 

 

 

 Cockpit + webservice 

 

 

 Soap/XML ou Rest/Json 

 

 

 pelas telas do cockpit 

 

 

 independência da integração via webservice aliada à facilidade de contar com a interface visual pronta 

 

 

   

 

 

 consumo do webservice 

 

 

 adicionado à mensalidade, conforme negociação, se o Cockpit estiver em nuvem 

 

 

 

 

 5 

 

 

 Cockpit + exportação e importação de arquivo, inclusive layouts específicos 

 

 

 csv, planilha... 

 

 

 pelas telas do cockpit 

 

 

 capacidade de implementarmos conversores para layouts do cliente 

 

 

 necessidade de ação humana para exportar e importar os dados a partir do Cockpit 

 

 

   

 

 

 adicionado à mensalidade, conforme negociação, se o Cockpit estiver em nuvem 

 

 

 

 

 6 

 

 

 Motor de Cálculo 

 

 

 API (soap/xml) ou DLL 

 

 

 O motor funciona junto ao Cockpit 

 

 

 Aplica as fórmulas de cálculo em cada transação, já considerando as diferenças entre os Estados! 

 

 

   

 

 

 consumo via API ou instanciando uma DLL 

 

 

 Depende da arquitetura escolhida 

 

 

 

 

 

 Algumas observações sobre as formas de integração: 

 

 Vantagens de se adotar webservices : há uma maior independência entre as soluções, que podem operar com Sistemas Operacionais, linguagens e bancos distintos; 

 É importante que o cliente tenha direito de  aprovar as informações  providas pela Systax, antes que produzam efeitos. Então o integrador precisará construir interfaces para o usuário consultar e aprovar as regras. Essas interfaces já estão prontas e em constante evolução no “Systax Cockpit”, além de diversas outras funcionalidades. 

 Integração direta via banco de dados  – sem que o cliente tenha de permitir conexões ao seu banco (evitando preocupações quanto à segurança). Ou seja, o banco que fica “aberto” para a conexão é o do “Systax Cockpit” – uma aplicação web com um database específico que contém apenas as regras daquele cliente (a Systax também não abre os seus bancos principais para conexão de terceiros). O Cockpit, e o seu banco de dados, pode estar disponível para conexão “local” (instalado no cliente) ou “remoto” (em nuvem, seja na Systax ou em infra provida pelo parceiro/cliente). A aplicação “Systax Cockpit” é desenvolvida em .Net e o banco é MS-SQL (se em instalação local, pode ser a licença MS-SQL Express, sem custo). 

 

 

 Vantagens da integração via banco de dados:

 

 acelera a integração reduzindo o esforço necessário; 

 oferece um conjunto de recursos prontos ao usuário. 

 

 

 Desvantagens:

 

 é mais um componente (uma aplicação) na solução. 

 maior dependência quanto ao padrão de banco de dados (MS-SQL). 

 

 

 

 

 Pode-se adotar o Cockpit como interface de gestão do conteúdo, ou pode-se usar o cockpit apenas para executar os processos de comunicação (uso dos webservices) e disponibilizar o banco de dados sempre atualizado, ou seja, usar o cockpit apenas como processo de constante atualização do banco de dados, sem aproveitar a interface gráfica. 

 Recomendamos adotar o Cockpit para os casos em que se deseja fazer uso do Systax Motor de cálculo, que foi construído sobre essa interface e banco de dados.

Arquitetura - Opções
Algumas possibilidades: 

 

 Integração por webservice 

 

 

   

 

 Integração usando o Systax Cockpit instalado no ambiente do cliente (junto ao ERP). 

 

 

   

 

 Integração usando o Systax Cockpit instalado em nuvem da Systax.

Webservices - Detalhes e Documentação
A Systax oferece alguns webservices, sendo que pelo menos 2 deles devem ser considerados no desenvolvimento de integrações (o webservice de manutenção dos cadastros de mercadorias e o de leitura das regras): 

 

 

 Parametrização Fiscal – é o webservice principal, para leitura do conteúdo (as regras tributárias). Arquivo de documentação do Webservice de Parametrização ERP: https://documentacao.systax.com.br/books/webservice-parametrizacao-fiscal 

 Cadastros – é o segundo webservice obrigatório, para manutenção do cadastro de mercadorias. Pode ser usado também para manutenção dos Grupos de Produtos (relação N-N entre mercadorias e Cenários) Documentação do Webservice de Cadastros: https://documentacao.systax.com.br/books/manual-cadastro-geral-cfm 

 

 

 Webservices opcionais  (solicite documentação específica se julgar necessário) 

 

 Cenários – apenas para leitura do conjunto de cenários de um cliente; 

 Consulta de regras “on demand” – produção síncrona de regras específicas, para resolver situações eventuais de “falta de regra”; 

 Relacionamento com o workflow de “Classificação Fiscal” - para trocas de mensagens do workflow, como receber dúvidas técnicas. Uso exclusivo para clientes que contratam o serviço adicional de revisão/atribuição de NCMs; 

 Leitura de sugestões de agrupamento de mercadorias – uso exclusivo quando o cliente contrata a Systax para analisar e decidir que itens devem ser tratados de forma agrupada. 

 Manutenção dos cadastros de clientes (uso exclusivo para Parceiros que irão ativar os acessos dos clientes finais) 

 

 

 Informações Importantes: 

 

 Nossos webservices são implementados com os padrões SOAP e XML, exceto a API implementada para leitura dos dados presentes no Cockpit, que é implementado com Rest/Json. 

 Pode-se testar a comunicação com a Systax. Para isso sugerimos que se use o SOAP-UI (instalador em  https://www.soapui.org/downloads/soapui.html  ), ou aplicação semelhante, para simular chamadas e conferir os resultados. 

 Se preferir, veja requisições de exemplo, incluídas no arquivo disponível para download: http://light.systax.com.br/download?file_d=request-soap 

 Veja também exemplos de código escritos em PHP, Java e .Net/C#, que implementam o consumo dos webservices: http://light.systax.com.br/download?file_d=tutorial-conexao-ws 

 

 

 Principais pontos de Atenção: 

 Em razão das experiências anteriores, com o acompanhamento a diversas integrações desenvolvidas conosco, destacamos alguns dos pontos que costumam exigir maior atenção para se evitar erros e retrabalhos: 

 

 Uso do “Ponteiro” – para viabilizar a atualização incremental da base de regras, transferindo “apenas o que mudou”, é importante a compreensão da lógica envolvida e alguns detalhes explicados no manual do webservice. Destacamos alguns pontos principais:

 

 O processo de atualização (leitura das regras) pode conter N requisições, já que o resultado é limitado ao tamanho da página (quantidade de regras entregues em cada resposta de requisição, limitada para evitar timeout). 

 Deve-se executar requisições adicionais, indicando o “id” do cenário e código de produto que retornou na última regra recebida da requisição anterior, até que a página de respostas volte com uma quantidade de regras inferior ao tamanho da paginação definida na requisição (o que indica que não há mais regras a serem transferidas). 

 Todas as requisições de um processo de atualização devem ser executadas indicando-se o mesmo “ponteiro” (aquele que foi gravado como resultado do processo anterior, normalmente do dia anterior), ou seja, da primeira à última requisição do processo, o mesmo ponteiro deve ser indicado (apenas o que vai variando é o “id” do cenário e o código do produto, que vão orientando a paginação dentro dos registros que estão sendo transferidos; 

 Cada resposta traz uma indicação de ponteiro. O processo deve guardar o primeiro ponteiro obtido (que vem na resposta à primeira requisição) para ser usado no processo do dia seguinte. Erro comum: guardar o último ponteiro obtido (o que veio com a última página do dia). Isso é necessário porque concomitante ao processo de leitura das regras a Systax pode estar incluindo regras novas ou alteradas na base, em páginas que já foram lidas. 

 

 

 Vigências – cada bloco de informações que tenha preenchimento (ICMS, Crédito de ICMS, etc.) possui no mínimo a data de início de vigência preenchida. O final de vigência só será informado se houver definição na legislação, então na maioria dos casos esse campo estará vazio. O processo de atualização vai lhe entregar regras novas ou alteradas, mas cabe ao usuário manter o histórico do seu lado, fechando vigência das regras anteriores, p.ex., se entender necessário. Em outras palavras: se mudou uma alíquota, a Systax só vai entregar a regra com a alíquota nova, não vamos entregar duas regras (a alíquota velha com vigência fechada + a regra com a alíquota nova). Do lado do cliente é que o acúmulo das regras vai formando uma base histórica. 

 Diferentes “origens” para a mesma mercadoria – Lembre-se que para a Systax a “chave” da tabela de mercadorias é: código_da_mercadoria + origem_da_mercadoria Ou seja: o EAN não é a chave; e podemos ter até nove registros com o mesmo código de mercadoria (origens de zero a oito, conforme tabela oficial) 

 NCM diferente entre o cadastro do cliente e a sugestão da Systax (projetos baseados em EAN): Especialmente para clientes do Systax LIGHT que operem com cadastros baseados em EAN, é importante entender que a NCM encaminhada pelo cliente à Systax é apenas um indicativo e não uma determinação. A Systax tem por tarefa buscar a NCM que consideramos correta para as mercadorias e não necessariamente seguir o que os fornecedores adotam. Pois há muita NCM errada circulando no mercado! Então na regra que retornamos constará a NCM que a Systax considera certa, podemos indicar ainda no campo observações que a NCM do cliente está diferente da nossa. Situações em que o cliente fizer questão de manter as NCMs do seu cadastro podem ser tratadas, mas exigirão um alinhamento prévio com a Systax, pois teremos de configurar isso em nosso sistema. E se tivermos de aceitar a NCM do cliente, a tributação que consideraremos levará em conta apenas a NCM e não mais a descrição. 

 Systax LIGHT e os itens “pendentes de Revisão” – é importante entender que o Systax LIGHT opera com valores bem inferiores aos nossos orçamentos de projetos, justamente porque a Systax não vai alocar consultores para tratar os dados do cliente. Mercadorias que sejam enviadas sem EAN, ou com EAN que não conhecemos, serão tratadas considerando-se apenas o código NCM (é premissa que a NCM esteja certa!), e entregaremos a tributação mais comum para aquela NCM. As imprecisões que podem surgir daí (nos casos em que uma NCM comporte diferentes tributações) podem ser minimizadas pela ação do cliente através de uma tela de consulta que disponibilizamos, onde poderão associar a mercadoria do cliente com itens mais específicos, pesquisados diretamente na base de dados da Systax. Nessa mesma tela poderá ser consultado um resumo estatístico do cadastro, indicando o total de mercadorias, quantas foram resolvidas pelo EAN, quantas foram resolvidas pela NCM (sãs as “pendentes de revisão”) e eventualmente os itens com NCMs inválidas. 

 Criação de cenários –os cenários de operação são criados automaticamente para quem contratar pacotes básicos do LIGHT (apenas um cenário de saída, em uma UF). Para clientes que contratam projetos, nossos consultores criarão os cenários alinhando os detalhes com os clientes. Para casos eventuais, pode-se solicitar a criação de cenários através de acionamento do nosso suporte. Mas em alguns casos pode-se preferir automatizar a criação de cenários, principalmente se for uma necessidade frequente. Isso pode ser feito, mas exigirá um entendimento prévio com a Systax, pelas questões técnicas e também comerciais.

Cockpit Systax - Detalhes e Documentação
Conceito 

 O Cockpit da Systax não deve ser entendido como parte do serviço SYSTAX. Ele não faz parte do lado “servidor” da nossa solução e sim é um componente para ficar no lado “cliente”, como uma alternativa aos clientes que não possuem um ERP integrado ou como um facilitador para integrações via banco de dados. Mesmo quando o Cockpit é oferecido instalado em nuvem, na infraestrutura da Systax, ele não está no mesmo ambiente dos servidores que geram as regras da Systax. E a comunicação entre o Cockpit e a Systax obedece às mesmas regras (webservices, premissas, limites) que qualquer outro cliente teria para acessar a solução da Systax. Se a adoção do Cockpit está sendo avaliada como alternativa de integração, sugerimos que se navegue pelo Cockpit para conhecer a aplicação: Acesse  http://cockpit.systax.com.br  e utilize os dados abaixo para autenticar-se: 

 

 Username: superdemo@systax.com.br 

 Senha: super123 

 

 Veja um documento com o dicionário de dados do database do Cockpit: https://www.systax.com.br/download/SystaxBancoDadosCockpit234.pdf 

 Sugestão de requisito de hardware para instalação local do Cockpit: 

 O aplicativo .Net deve ser instalado em um servidor Windows, podendo ser no mesmo servidor que vai ficar o banco de dados SQL Server. 

 

 Windows Server 2008 ou Windows Server 2008 R2 - 64bits ou superior; 

 SQL Server 2008 ou 2012 (pode ser versão Express); 

 4 cores ou superior; 

 400 GB de disco ou superior; 

 8GB de memória; 

 

 Sobre o Banco de dados: SQL Server -> O Instalador oferece opção do SQL Server Express que é gratuito para bases de até 10GB, ou se tiver um banco de dados é solicitado as credencias de acesso para  criação de novo database . 

 Na instalação vai pedir username e senha para acesso ao webservice de leitura das regras. O acesso ao Cockpit Local (depois de instalado) será pelo endereço  http://localhost/Cockpit /  indicando: 

 Username:  administrador@systax.com.br senha: systax@123 

 Cadastro de novos produtos através do Cockpit: 

 Os novos produtos devem ser inseridos na tabela “tbl_carga_produto”. O Cockpit local insere os produtos dessa tabela na base remota da Systax e preenche o campo idProtocolo que representa evidência do recebimento no cadastro da base Systax. 

 Consulta de regras tributárias No link abaixo pode ser obtido documento com exemplos de queries para retorno de regras tributárias, de acordo com apresentação do Cockpit. Inclui todos os campos e tributos, tratando regras aprovadas, pendentes e controle de data da atualização: 

 https://documentacao.systax.com.br/books/manual-de-integracao-via-banco-de-dados/chapter/exemplos-de-queries-para-retorno-de-regras-da-reforma-tributaria