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

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

3. Cenários – apenas para leitura do conjunto de cenários de um cliente;
4. Consulta de regras “on demand” – produção síncrona de regras específicas, para resolver situações eventuais de “falta de regra”;
5. 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;
6. 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.
7. 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.