Manual do Tax Validator

Manual contendo as últimas atualizações efetuadas em 24/11/2023.

Introdução
Acesso
Autenticação
Descrição dos campos de chamada e retorno
Dados do Cenário
Como gerar a regra tributária?

Introdução

O objetivo dessa API é validar a tributação do documento emitido considerando a regra parametrizada no Cockpit ou via on demand.

A validação será feita nos tributos ICMS, ICMSST, IPI, PIS e Cofins.

As diferenças de campos serão apontadas nas Tags diferencas_ICMS (aqui estarão ICMS e ICMSST), diferencas_IPI, diferencas_PIS, diferencas_Cofins e diferencas_ICMSUFDest

As diferenças de valores serão apontadas nas Tags: valor_diferenca_ICMS, valor_diferenca_ICMS_ST, valor_diferenca_IPI, valor_diferenca_PIS, valor_diferenca_Cofins e valor_diferenca_ICMSUFDest.

Acesso

Para acessar a coleção de chamadas Clique Aqui.

Swagger: https://wscockpit.systax.com.br/api/swagger/index.html

Listagem dos Endpoints que contemplam o manual do Tax Validator.

Grupo Swagger	Método	URL Endpoint	URL Token
TaxValidator	POST	https://wscockpit.systax.com.br/apiHomologacao/api/TaxValidator	https://app.systax.com.br/auth/access-token
TaxValidator	POST	https://wscockpit.systax.com.br/api/api/TaxValidator	https://app.systax.com.br/auth/access-token

Autenticação

A autenticação pode ser feita através do Token ou usuário e senha. O Token gerado deve ser enviado por autenticação “Bearer Token”.

Por usuário e senha, basta utilizar autenticação “Basic Auth”.

Importante: A autenticação “Basic Auth” deve ser feito com as credenciais do cockpit, enquanto a autenticação “Bearer Token” é com as credenciais de acesso ao site Systax.

Descrição dos campos de chamada e retorno

Chamada

Obs: O XML deve ser incluído inteiro na chamada, entre aspas simples.

Layout Request:

{

"documento": ''

}

Retorno

Campo	Descrição
data_envio	Data da validação
Chave	chave de acesso do Documentos eletrônico
qtd_itens	quantos produtos existem no Documento
qtd_itens_validados	quantos produtos foram validados
Itens	quantos campos foram validados
Chave	chave de acesso do Documentos eletrônico
cnpj_emit	CNPJ do emitente do documento
cnpj_dest	CNPJ do destinatário do documento
nFe_dhEmi	Data da emissão da NF-e
entSai	Se é entrada ou saída (0 - Entrada / 1 - Saída)
ufOrig	UF de Origem
ufDest	UF de Destino
Mod	modelo do Documento eletrônico
indFinal	Indica se o destinatário é consumidor final ou não
crt_emit	Indica se o emitente é do Simples Nacional, RPA ou Simples com limite excedido.
mun_emit	Município emitente
mun_dest	Município destinatário
valor_item	valor do produto
Sn	Se identificamos o emitente como Simples Nacional (S - Sim / N - Não)
Ean	EAN do produto
Orig	Origem do produto
Ncm	NCM do produto
Extipi	Ex TIPI do produto
nat_op	Natureza de Operação definida na determinação de perfil
perfRem	Ex_Origem definido na determinação de perfil
perfDest	Ex_Destinação definido na determinação de perfil
xProd	Descrição do Produto
qTrib	quantidade do produto
cProd	código do produto
uCom	unidade comercial
qCom	quantidade comercial
vUnCom	valor unitário comercial
uTrib	unidade tributável
nfE_CFOP	CFOP da NF-e
taX_CFOP	CFOP Systax
nFe_CEST	CEST da nFe
tax_CEST	CEST da tax
diferencas_ICMS	tags com diferencas
nFe_ICMS_CST	ICMS_CST da nFe
tax_ICMS_CST	ICMS_CST da tax
nFe_ICMS_modBC	ICMS_modBC da nFe
tax_ICMS_modBC	ICMS_modBC da tax
nFe_ICMS_pDif	ICMS_pDif da nFe
tax_ICMS_pDif	ICMS_pDif da tax
nFe_ICMS_pICMS	ICMS_pICMS da nFe
tax_ICMS_pICMS	ICMS_pICMS da tax
nFe_ICMS_pICMSST	ICMS_pICMSST da nFe
tax_ICMS_pICMSST	ICMS_pICMSST da tax
nFe_ICMS_pMVAST	ICMS_pMVAST da nFe
tax_ICMS_pMVAST	ICMS_pMVAST da tax
nFe_ICMS_pRedBC	ICMS_pRedBC da nFe
tax_ICMS_pRedBC	ICMS_pRedBC da tax
nFe_ICMS_pRedBCST	ICMS_pRedBCST da nFe
tax_ICMS_pRedBCST	ICMS_pRedBCST da tax
nFe_ICMS_vBC	ICMS_vBC da nFe
tax_ICMS_vBC	ICMS_vBC da tax
nFe_ICMS_vBCST	ICMS_vBCST da nFe
tax_ICMS_vBCST	ICMS_vBCST da tax
nFe_ICMS_vICMS	ICMS_vICMS da nFe
tax_ICMS_vICMS	ICMS_vICMS da tax
nFe_ICMS_pFCP	ICMS_pFCP da nFe
tax_ICMS_pFCP	ICMS_pFCP da tax
nFe_ICMS_vBCFCP	ICMS_vBCFCP da nFe
tax_ICMS_vBCFCP	ICMS_vBCFCP da tax
nFe_ICMS_vFCP	ICMS_vFCP da nFe
tax_ICMS_vFCP	ICMS_vFCP da tax
valor_diferenca_ICMS	Valor da diferenças de ICMS
nFe_ICMS_vICMSDeson	ICMS_vICMSDeson da nFe
tax_ICMS_vICMSDeson	ICMS_vICMSDeson da tax
nFe_ICMS_vICMSDif	ICMS_vICMSDif da nFe
tax_ICMS_vICMSDif	ICMS_vICMSDif da tax
nFe_ICMS_vICMSOp	ICMS_vICMSOp da nFe
tax_ICMS_vICMSOp	ICMS_vICMSOp da tax
nFe_ICMS_vICMSST	ICMS_vICMSST da nFe
tax_ICMS_vICMSST	ICMS_vICMSST da tax
nFe_ICMS_pFCPST	ICMS_pFCPST da nFe
tax_ICMS_pFCPST	ICMS_pFCPST da tax
nFe_ICMS_vBCFCPST	ICMS_vBCFCPST da nFe
tax_ICMS_vBCFCPST	ICMS_vBCFCPST da tax
nFe_ICMS_vFCPST	ICMS_vFCPST da nFe
tax_ICMS_vFCPST	ICMS_vFCPST da tax
valor_diferenca_ICMS_ST	Valor da diferença de ICMSST
diferencas_PIS	tags com diferencas PIS
nfe_PIS_CST	PIS_CST da nfe
tax_PIS_CST	PIS_CST da tax
nfe_PIS_vBC	PIS_vBC da nfe
tax_PIS_vBC	PIS_vBC da tax
nfe_PIS_pPIS	PIS_pPIS da nfe
tax_PIS_pPIS	PIS_pPIS da tax
nfe_PIS_qBCProd	PIS_qBCProd da nfe
tax_PIS_qBCProd	PIS_qBCProd da tax
nfe_PIS_vAliqProd	PIS_vAliqProd da nfe
tax_PIS_vAliqProd	PIS_vAliqProd da tax
nfe_PIS_vPIS	PIS_vPIS da nfe
tax_PIS_vPIS	PIS_vPIS da tax
valor_diferenca_PIS	Valor da diferença de PIS
diferencas_COFINS	Tags com diferenças COFINS
nFe_COFINS_CST	COFINS_CST da nFe
tax_COFINS_CST	COFINS_CST da tax
nFe_COFINS_vBC	COFINS_vBC da nFe
tax_COFINS_vBC	COFINS_vBC da tax
nFe_COFINS_pCOFINS	COFINS_pCOFINS da nFe
tax_COFINS_pCOFINS	COFINS_pCOFINS da tax
nFe_COFINS_qBCProd	COFINS_qBCProd da nFe
tax_COFINS_qBCProd	COFINS_qBCProd da tax
nFe_COFINS_vAliqProd	COFINS_vAliqProd da nFe
tax_COFINS_vAliqProd	COFINS_vAliqProd da tax
nFe_COFINS_vCOFINS	COFINS_vCOFINS da nFe
tax_COFINS_vCOFINS	COFINS_vCOFINS da tax
valor_diferenca_COFINS	Valor da diferenças COFINS
diferencas_IPI	Tags com diferença IPI
nFe_IPI_CST	IPI_CST da nFe
tax_IPI_CST	IPI_CST da tax
nFe_IPI_cEnq	IPI_cEnq da nFe
tax_IPI_cEnq	IPI_cEnq da tax
nFe_IPI_vBC	IPI_vBC da nFe
tax_IPI_vBC	IPI_vBC da tax
nFe_IPI_pIPI	IPI_pIPI da nFe
tax_IPI_pIPI	IPI_pIPI da tax
nFe_IPI_qUnid	IPI_qUnid da nFe
tax_IPI_qUnid	IPI_qUnid da tax
nFe_IPI_vUnid	IPI_vUnid da nFe
tax_IPI_vUnid	IPI_vUnid da tax
nFe_IPI_vIPI	IPI_vIPI da nFe
tax_IPI_vIPI	IPI_vIPI da tax
valor_diferenca_IPI	Valor da diferença de IPI
vProdOriginal	dOriginal da vPr
origem_regra	em_regra da ori
numero_nfe	ro_nfe da num
serie_nfe	e_nfe da ser
diferencas_ICMSUFDest	Tags com diferenças UFDest
tax_vBCUFDest	vBCUFDest da tax
tax_vBCFCPUFDest	vBCFCPUFDest da tax
tax_pFCPUFDest	pFCPUFDest da tax
tax_pICMSUFDest	pICMSUFDest da tax
tax_pICMSInter	pICMSInter da tax
tax_pICMSInterPart	pICMSInterPart da tax
tax_vFCPUFDest	vFCPUFDest da tax
tax_vICMSUFDest	vICMSUFDest da tax
tax_vICMSUFRemet	vICMSUFRemet da tax
tax_pRedBC_UFDest	pRedBC_UFDest da tax
nFe_vBCUFDest	vBCUFDest da nFe
nFe_vBCFCPUFDest	vBCFCPUFDest da nFe
nFe_pFCPUFDest	pFCPUFDest da nFe
nFe_pICMSUFDest	pICMSUFDest da nFe
nFe_pICMSInter	pICMSInter da nFe
nFe_pICMSInterPart	pICMSInterPart da nFe
nFe_vFCPUFDest	vFCPUFDest da nFe
nFe_vICMSUFDest	vICMSUFDest da nFe
nFe_vICMSUFRemet	vICMSUFRemet da nFe
valor_diferenca_vFCPUFDest	Valor da diferente no valor do FCP do UFDest
valor_diferenca_vICMSUFDest	Valor da diferença no valor do UFDest
valor_diferenca_vICMSUFRemet	Valor da diferença no valor do UFDest Remetente
Sucesso
Mensagem

Dados do Cenário

Dados: cProd, EAN, NCM, Origem do Produto.

Notas recebidas

Com os dados do produto, vamos identificar o produto para a validação.

Se o documento validado tiver a tag tpNF=1 e o destinatário for o cliente Systax, vamos buscar o código informado na tag cProd na tabela de De-Para que existe no site Systax no cadastro do nosso cliente.

Nessa tabela temos o CNPJ do fornecedor e o código de produto do fornecedor com o código de produto correspondente do nosso cliente.

Se encontrarmos, seguimos a validação considerando o código de produto de nosso cliente, se não houver dado na tabela de De-Para, buscamos produtos na base centralizada com EAN e, se não encontrarmos, buscamos pela NCM e nesse caso a tributação será mais genérica, visto que vamos considerar o produto padrão dessa NCM.

Notas emitidas

Quando a nota é emitida por nosso cliente, o cProd estará preenchido com o código de produto que deverá ser tratado na base de regras parametrizadas para esse cliente.

Dessa forma, vamos considerar o valor da tag cProd para localizar o produto direto na base do cliente no site, caso não exista, vamos seguir com a busca na base centralizada, sendo o EAN primeiro e, se não existir produto com esse EAN, buscamos um produto padrão para a NCM.

Como gerar a regra tributária?

Com os dados do cenário e produtos definidos, o sistema criará uma chamada no motor de cálculo que buscará uma regra no Cockpit do cliente e, caso não encontre, acionará o cálculo de regras on demand.

Com o cálculo finalizado, o Tax Validator fará uma comparação entre os dados gerados no motor de cálculo e os dados enviados no XML que está sendo submetido a validação.

*Vide = “Cálculo on demand” no link abaixo, para entender como são feitas as chamadas on demand:

https://documentacao.systax.com.br/books/api-regra-on-demand

Como a comparação é apresentada:

A API apresentará os dados do cenário nas primeiras tag:

A API retorna com todos os campos que poderão ser comparados no documento eletrônico, intercalando entre NF-e e Tax, todas as tag que iniciam com Tax são referentes ao dado da regra e/ou cálculo da Systax.

Os tributos estão por blocos, dessa forma, cada bloco de tributo apresentará no início do bloco “Diferenças_XXXX” e no final de cada bloco retornará “Valor_diferenca_XXXX”

Diferenças_XXXXX = São as tags que apresentaram diferenças.

Valores_diferenca_XXXX = São os valores de diferenças, sempre que estiver negativo é porque o XML demonstra um valor menor que a regra da Systax e sendo positivo, o XML está a maior que a regra da Systax.

Blocos validados

ICMS

ICMSST

IPI

PIS

COFINS

UF_Dest

Outras informações

A API informará com quais dados a validação foi feita, se foi feita com regra da base do cliente ou se foi via on demand:

Informará também, quantos itens foram validados.