A classe TCIWritten (Tax Configurator Integration Written) foi desenvolvida para viabilizar o acesso aos dados gravados nas tabelas F2D (Tributos Genéricos Calculados) e CJ3 (Tabela Escrituracao por item) do Configurador de Tributos (FISA170) de uma forma dinâmica e intuitiva.
Este documento tem o objetivo de demonstrar o funcionamento da classe TCIWritten e seus os métodos.
Todos os exemplos demonstrados nesta documentação são fictícios, criados com intuito de orientar, cabendo ao desenvolvedor aplicar os conceitos demonstrados da forma que atenda plenamente as necessidades da operação. |
A classe TCIWritten facilita a recuperação de dados específicos das tabelas F2D e CJ3 utilizando métodos que permitem o acesso aos registros por meio de IDs. O retorno dos dados é estruturado no formato JSON, tornando-o fácil de manipular e integrar com outras partes de uma aplicação.
Ao inicializar a MATXFIS usando a função MafisIni na rotina de inclusão de documentos de entrada ou saída, é necessário informar que a rotina está apta a processar o configurador de tributos. Essa informação deve ser passada no parâmetro 33.
Por exemplo:
// Valida a utilização do configurador de tributos
// lCalcTG: variável lógica que indica se a função ChkTrbGen foi encontrada e executada com sucesso
lCalcTG := IIf(FindFunction("ChkTrbGen"), ChkTrbGen("SD2","D2_IDTRIB"), .F.)
//Inicia os calculos da Matxfis
MaFisIni(SA1->A1_COD, SA1->A1_LOJA, cTipoPar,cTipoNf, SA1->A1_TIPO , MaFisRelImp("MT100",{"SF2","SD2"}),,.T.,,,,,,,,,,,,,,,,,,,,,,,,,lCalcTG)
//...Corpo da função...
// Grava o campo responsável pelo relacionamento do item com o configurador de tributos
If lTrbGen
SD2->D2_IDTRIB := MaFisTG(1,"SD2",nY)
EndIf |
A função ChkTrbGen responsável por efetuar algumas validações para utilização dos tributos genéricos.
Parâmetros
A função MaFisTG é responsável pela gravação e exclusão dos tributos calculados pelo configurador de tributos.
Parâmetros
Para utilizar a classe, instancie um objeto da classe TCIWritten, utilizando namespace totvs.protheus.backoffice.fiscal.tciclass e utilize os métodos disponíveis para informar o ID (ou IDs) dos registros que deseja obter. Os dados serão retornados no formato JSON.
Para mais informações sobre o uso de namespaces, consulte o manual Namespace. Classes em TLPP que herdam de classe com namespace precisam utilizar o namespace na declaração da classe ou utilizar o namespace no programa que executa a chamada da classe. Para fontes escritos em TLPP, pode adicionar o namespace no início do arquivo fonte. Por exemplo:
Para fontes escritos em ADVPL deve ser utilizado por extendo o namespace + classe.
|
O construtor da classe. Inicializa um novo objeto da classe TCIWritten.
Utilização
oDados := TCIWritten():New() |
Define os IDs dos registros que se deseja obter os dados. Pode ser um único ID ou uma lista de IDs.
Parâmetros
Utilização
// Definindo um único ID
aData := {"369ca132-2b3b-ac96-6b78-3247afcc2219"}
oDados := TCIWritten():New()
oDados:SetId(aData)
// Definindo múltiplos IDs
aData1 := {"369ca132-2b3b-ac96-6b78-3247afcc2219","a5dcda40-d145-28d1-c57f-1047e15ce1fe"}
oDados := TCIWritten():New()
oDados:SetId(aData1) |
Recupera os dados dos registros informados em 𝚜𝚎𝚕𝚏:𝚊𝙸𝚍𝚁𝚎𝚚𝚞𝚎𝚜𝚝
Para o correto funcionamento do método GetDataId() é imprescindível informar o(s) ID(s) que deseja os dados através do método SetId(), caso contrário será retornado uma mensagem: "erro - Necessita informar Id" Quando um id inválido é informado em SetId(aIds as Array), GetDataId() retornará um objeto JSON com a chave "Aviso" e o valor "Id não calculado pelo configurador de tributos". Exemplo:
A chamada acima retornará um objeto como este: |
Retorno
{
"dados_Id": {
"fd32a6d9-70fa-6b68-18b5-cc17375d15b3": {
"TG_001": {
"filial": "XIFIS26",
"tributo": "TG0002",
"codigo_tributo_relacionado": "",
"descricao_tributo_relacionado": "",
"base_tributo": 0,
"aliquota_tributo": 10,
"valor_tributo": 80,
"valor_urf": 10,
"mva": 0,
"valor_pauta": 0,
"percentual_majora": 0,
"indice_aux_majora": 0,
"tributo_majora": "",
"aliquota_majora": 0,
"valor_majora": 0,
"ded_dependentes": 0,
"id_cadastro_regra_tributo": "4201ee25-972f-5840-9feb-2df327f3982d"
"dados_escriturados": {
"filial": "",
"codigo_tributo": "",
"valor_tributado": 0,
"cst": "",
"valor_isento": 0,
"valor_outros": 0,
"valor_nao_tributado": 0,
"valor_diferido": 0,
"valor_majorado": 0,
"perc_majorado": 0,
"perc_diferido": 0,
"perc_reducao": 0,
"valor_pauta": 0,
"mva": 0,
"ind_aux_mva": 0,
"Ind_aux_majora": 0,
"codigo_tab_cst": "",
"valor_base_original": 0
},
"regras_base": {
"codigo_regra": "BAS021",
"descricao": "Base ICMS ST RED. 41,67% ",
"acao_origem": "11",
"acao_desconto": "1",
"acao_frete": "1",
"acao_seguro": "1",
"acao_despesa": "1",
"acao_icms_desonerado": "1",
"acao_icms_retido": "1",
"perc_reducao": 41.67,
"tipo_reducao": " ",
"unidade_medida": " ",
"formula_base": "( ( O:VAL_MERCADORIA * I:PERC_REDUCAO_BASE ) * I:MVA )",
"id_formula": "c706aeb1-3f33-c97c-71df-87b1edff2d88",
"codigo_formula": "B:BAS021"
},
"regras_aliquota": {
"codigo_regra": "ALQ023",
"descricao": "ALIQUOTA PADRAO DE 20% ",
"acao_origem": "04",
"acao_tipo": "1",
"perc_aliquota": 20,
"codigo_urf": " ",
"perc_urf": 0,
"formula_aliquota": "20",
"id_formula": "9d86e6bc-6a3c-9ea8-8053-57b2eb7eb045",
"codigo_fomula": "A:ALQ023"
},
"regras_escrituracao": {
"codigo_regra": "ESC013",
"descricao": "ICMS Tributado Redução em Isento CST 70 ",
"acao_incidencia": "2",
"acao_total_nf": "6",
"perc_diferimento": 0,
"incidencia_parc_red": " ",
"tabela_cst": "000001",
"cst": "70 ",
"cst_devolucao": "70 "
}
},
"TG_00N": { ... },
}, |
Descrição das propriedades contidas no tributo
| Propriedade | Tipo | Descrição |
|---|---|---|
| filial | caractere | Filial da operação |
| tributo | caractere | Sigla do tributo |
| codigo_tributo_relacionado | caractere | Código do tributo relacionado |
| descricao_tributo_relacionado | caractere | Descrição do tributos relacionado |
| base_tributo | número | Valor da base do tributo |
| aliquota_tributo | número | Alíquota do tributo |
| valor_tributo | número | Valor do tributo |
| valor_urf | número | Valor da URF |
| mva | número | Valor do MVA |
| valor_pauta | número | Valor pauta |
| percentual_majora | número | Percentual majorado |
| indice_aux_majora | número | Índice auxiliar majoração |
| tributo_majora | caractere | Tributo majorado |
| aliquota_majora | número | Alíquota majorada |
| valor_majora | número | Valor majorado |
| ded_dependentes | número | Dedução por dependentes |
| id_cadastro_regra_tributo | caractere | Id do cadastro do tributo |
| dados_escriturados | json | |
| regras_base | json | |
| regras_aliquota | json | |
| regras_escrituracao | json |
Objeto dados_escriturados
| Atributo | Tipo | Descrição |
|---|---|---|
| filial | caractere | Filial da operação |
| valor_tributado | número | Valor tributado |
| cst | caractere | CST |
| valor_isento | número | Valor isento |
| valor_outros | número | Valor outros |
| valor_nao_tributado | número | Valor não tributado |
| valor_deferido | número | Valor deferido |
| valor_majorado | número | Valor majorado |
| perc_majorado | número | Percentual majorado |
| perc_diferido | número | Percentual diferimento |
| perc_redução | número | Percentual redução |
| valor_pauta | número | Valor pauta |
| mva | número | MVA |
| ind_aux_mva | número | Índice auxiliar MVA |
| ind_aux_majora | número | Índice auxiliar majorado |
| codigo_tab_cst | caractere | Cod. Tabela CST |
| valor_base_original | número | Valor base original |
Objeto regras_base
| Atributo | Tipo | Descrição |
|---|---|---|
| codigo_regra | caractere | Código da regra |
| descricao | caractere | Descrição da regra |
| acao_origem | caractere | Valor de Origem |
| acao_desconto | caractere | Ações do Desconto |
| acao_frete | caractere | Ações do valor do frete |
| acao_seguro | caractere | Ações do valor de Seguro |
| acao_despesa | caractere | Ações das Despesas |
| acao_icms_desonerado | caractere | Ações ICMS Desonerado |
| acao_icms_retido | caractere | Ações ICMS Retido |
| perc_reducao | número | Percentual de redução |
| tipo_reducao | caractere | Tipo da redução |
| unidade_medida | caractere | Unidade de medida |
| formula_base | caractere | Fórmula da base |
| id_formula | caractere | Identificador da fórmula |
| codigo_formula | caractere | Código da fórmula |
Para mais informações sobre o conteúdo dos campos verificar a documentação: CFGTRIB - Configurador de Tributos (Regras de base de cálculo) |
Objeto regras_aliquota
| Atributo | Tipo | Descrição |
|---|---|---|
| codigo_regra | caractere | Código da regra |
| descricao | caractere | Descrição da regra |
| acao_origem | caractere | Valor de Origem |
| acao_tipo | caractere | Tipo de Alíquota |
| perc_aliquota | número | Alíquota |
| codigo_urf | caractere | Código da URF |
| perc_urf | número | Percentual da URF |
| formula_aliquota | caractere | Fórmula da alíquota |
| id_formula | caractere | Identificador da fórmula |
| codigo_fomula | caractere | Código da fórmula |
Para mais informações sobre o conteúdo dos campos verificar a documentação: |
Objeto regras_escrituracao
| Atributo | Tipo | Descrição |
|---|---|---|
| codigo_regra | caractere | Código da regra |
| descricao | caractere | Descrição da regra |
| acao_incidencia | caractere | Opcao de Incidência |
| acao_total_nf | caractere | Soma no total da nota |
| perc_diferimento | número | Percentual do Diferimento |
| incidencia_parc_red | caractere | Indidencia Redução Base |
| tabela_cst | número | Tabela de CST |
| cst | caractere | Classificação fiscal |
| cst_devolucao | caractere | CST de Devolução |
Para mais informações sobre o conteúdo dos campos verificar a documentação: |
Utilização
aIds := {"fd32a6d9-70fa-6b68-18b5-cc17375d15b3"}
cResponse := ""
oDados := TCIWritten():New()
oDados:SetId(aIds)
cResponse := oDados:GetDataId() |
Permite adicionar ao retorno de GetDataId() detalhes das configurações realizadas pelo usuário no Configurador de Tributos (FISA170).
Parâmetros
O uso do método setDataItems() se faz necessário apenas quando há a necessidade obter dados de cadastros no Configurador de Tributos (FISA170), não sendo obrigatório para a obtenção dos tributos dos itens. Quando necessário, o método setDataItems() deve ser chamado antes de GetDataId(). Se os valores informados no parâmetro aContent divergirem dos valores permitidos, será adicionado o objeto erro_propriedade descrevendo a propriedade inválida informada:
A chamada acima retornará um objeto como este: |
Utilização
using totvs.protheus.backoffice.fiscal.tciclass
Function Exemplo()
Local oDados as json
Local cRetorno
oDados := TCIWritten():New()
oDados:setDataItems({"regras_base", "regras_aliquota", "regras_escrituracao"})
cRetorno := oDados:GetDataId()
Return cRetorno |
Altera o o retorno do GetDataId(), para retornar um JSON indexado por regras de cálculo (F2B_REGRA).
*Pode-se utilizar em conjunto com o método setTaxRuleFilterList() para filtrar, passando por parâmetro quais regras de cálculo se deseja no retorno.
**Pode-se utilizar em conjunto com o método setAdditionalFieldsToReturn() para adicionar campos no retorno, passando por parâmetro quais atributos se deseja receber além do retorno padrão;
Os métodos setTaxRuleFilterList() e setAdditionalFieldsToReturn() irão apenas funcionar no contexto dos retornos simplificados: setReturnByTaxRule() e setReturnByIdTotvs(). Eles não tem efeito no retorno padrão do GetDataId(). |
Utilização
aData := {"DD227D08-AECE-4F11-BE55-AC5AFCAF013F","A7A15DCF-C1B8-4F11-9E54-AC5AFCAF013F","30DE92B8-C9B8-4F11-8E54-AC5AFCAF013F"}
aFieldsNeeded := {'dados_escriturados','mva','regras_escrituracao'}
aTribs := {'PISTG','COFTG'}
oDados := TCIWritten():New()
oDados:SetId(aData)
oDados:setReturnByTaxRule() // Altera o retorno do método :GetDataId()
oDados:setAdditionalFieldsToReturn( aFieldsNeeded ) // Opcional: Adicionar mais campos no retorno do objeto
oDados:setTaxRuleFilterList( aTribs ) // Opcional: Filtra o retorno somente com as regras de cálculo que se deseja
CONOUT( oDados:GetDataId() )
/*
{
"COFTG":{
"items":{
"DD227D08-AECE-4F11-BE55-AC5AFCAF013F":{
"regra_trib":"COFTG",
"filial":"XIFIS26",
"codigo_tributo_relacionado":"000016",
"tributo":"COF",
"descricao_tributo_relacionado":"CONTRIBUI O PARA FINANCIAMENTO DA SEGURIDADE SOCIAL",
"base_tributo":1000,
"aliquota_tributo":7.6,
"valor_tributo":76,
"dados_escriturados":{
},
"mva":0,
"regras_escrituracao":"regra nao vinculada"
},
"A7A15DCF-C1B8-4F11-9E54-AC5AFCAF013F":{
},
"30DE92B8-C9B8-4F11-8E54-AC5AFCAF013F":{
}
}
},
"PISTG":{
"items":{
"DD227D08-AECE-4F11-BE55-AC5AFCAF013F":{
},
"A7A15DCF-C1B8-4F11-9E54-AC5AFCAF013F":{
},
"30DE92B8-C9B8-4F11-8E54-AC5AFCAF013F":{
}
}
}
}
*/ |
Altera o o retorno do GetDataId(), para retornar um JSON indexado por tributos com ID Totvs (F2C_CODIGO).
*Pode-se utilizar em conjunto com o método setIdTotvsFilterList() para filtrar, passando por parâmetro quais ID Totvs se deseja no retorno.
**Pode-se utilizar em conjunto com o método setAdditionalFieldsToReturn() para adicionar campos no retorno, passando por parâmetro quais atributos se deseja receber além do retorno padrão;
Os métodos setIdTotvsFilterList() e setAdditionalFieldsToReturn() irão apenas funcionar no contexto dos retornos simplificados: setReturnByTaxRule() e setReturnByIdTotvs(). Eles não tem efeito no retorno padrão do GetDataId(). |
Utilização
aData := {"DD227D08-AECE-4F11-BE55-AC5AFCAF013F","A7A15DCF-C1B8-4F11-9E54-AC5AFCAF013F","30DE92B8-C9B8-4F11-8E54-AC5AFCAF013F"}
aFieldsNeeded := {'mva','regras_escrituracao'}
oDados := TCIWritten():New()
oDados:SetId(aData)
oDados:setReturnByIdTotvs() // Altera o retorno do método :GetDataId()
oDados:setAdditionalFieldsToReturn( aFieldsNeeded ) // Opcional: Adicionar mais campos no retorno do objeto
aTotvsId := {'000021'} // 000021 = ICMS
oDados:setIdTotvsFilterList( aTotvsId ) // Opcional: Filtra o retorno somente o ID totvs que se deseja
CONOUT( oDados:GetDataId() )
/*
{
"000021":{
"items":{
"DD227D08-AECE-4F11-BE55-AC5AFCAF013F":{
"regra_trib":"ICMSTG",
"filial":"XIFIS26",
"codigo_tributo_relacionado":"000021",
"tributo":"ICMS",
"descricao_tributo_relacionado":"ICMS - Imposto sobre Circula o de Mercadorias e Servi os",
"base_tributo":1000,
"aliquota_tributo":18,
"valor_tributo":180,
"mva":0,
"regras_escrituracao":{
"codigo_regra":"TESTE",
"descricao":"REGRA DE ESCRITURACAO",
"acao_incidencia":"1",
"acao_total_nf":"5",
"perc_diferimento":0,
"incidencia_parc_red":" ",
"tabela_cst":"000001",
"cst":"00",
"cst_devolucao":"00"
}
},
"A7A15DCF-C1B8-4F11-9E54-AC5AFCAF013F":{
},
"30DE92B8-C9B8-4F11-8E54-AC5AFCAF013F":{
}
}
}
}
*/ |
O método getAgregTypeByTax( cTipoIncidencia , cCodTribIdTotvs ) permite receber de forma simples qual foi o tipo de incidência sobre o total da NF (CJ2_STONF) para cada tributo, dentro de cada item de um documento.
Parâmetros:
cTipoIncidencia: (String) (Opcional) - Busca e filtra o retorno de acordo com um tipo válido de incidência sobre total da NF (atualmente de 1 à 8).
cCodTribIdTotvs : (String) (Opcional) - Busca e filtra o retorno de acordo com um tipo válido de código de tributo (ID Totvs = F2C_CODIGO na tabela F2C).
*Caso não seja informado nenhum parâmetro, irá trazer todos os registros encontrados, independente de tipo de incidência e tributo Id Totvs.
*Obrigatório a chamada do método oDados:setDataItems({"regras_escrituracao"}) antes da chamada do getAgregTypeByTax(), para os dados de escrituração estarem disponíveis.
As opções de incidência atualmente são:
| 1 | Sem Ação |
| 2 | Subtrai somente do total da nota |
| 3 | Subtrai do total da nota e da duplicata |
| 4 | Subtrai somente do total da duplicata |
| 5 | Soma somente no total da nota |
| 6 | Soma no total da nota e da duplicata |
| 7 | Soma somente no total da duplicata |
| 8 | Gross up no total da duplicata |
Utilização sem passar parâmetros:
oDados := TCIWritten():New()
aData := {"6D76CB61-2AEE-4F11-9E56-AC5AFCAF013F","ADE403B0-D7F2-4F11-8E56-AC5AFCAF013F"}
oDados:SetId(aData)
oDados:setDataItems({'regras_escrituracao'}) //obrigatorio
oDados:GetDataId() // opcional
cResponse := oDados:getAgregTypeByTax() |
Exemplo Retorno
{
"data":{
"6D76CB61-2AEE-4F11-9E56-AC5AFCAF013F":{
"COFTG":{
"acao_tot_nf":"2",
"id_totvs":"000016"
},
"PISTG":{
"acao_tot_nf":"3",
"id_totvs":"000015"
},
"ICMSTG":{
"acao_tot_nf":"5",
"id_totvs":"000021"
}
},
"ADE403B0-D7F2-4F11-8E56-AC5AFCAF013F":{
"COFTG":{
"acao_tot_nf":"2",
"id_totvs":"000016"
},
"PISTG":{
"acao_tot_nf":"3",
"id_totvs":"000015"
},
"ICMSTG":{
"acao_tot_nf":"5",
"id_totvs":"000021"
}
}
}
} |
Utilização com parâmetro de incidência sobre total da NF:
oDados := TCIWritten():New()
aData := {"6D76CB61-2AEE-4F11-9E56-AC5AFCAF013F","ADE403B0-D7F2-4F11-8E56-AC5AFCAF013F"}
oDados:SetId(aData)
oDados:setDataItems({'regras_escrituracao'}) //obrigatorio
oDados:GetDataId() // opcional
cResponse := oDados:getAgregTypeByTax("3") |
Exemplo Retorno
{
"data":{
"6D76CB61-2AEE-4F11-9E56-AC5AFCAF013F":{
"PISTG":{
"acao_tot_nf":"3",
"id_totvs":"000015"
}
},
"ADE403B0-D7F2-4F11-8E56-AC5AFCAF013F":{
"PISTG":{
"acao_tot_nf":"3",
"id_totvs":"000015"
}
}
}
} |
Utilização com parâmetro de código de tributo (Id Totvs):
oDados := TCIWritten():New()
aData := {"6D76CB61-2AEE-4F11-9E56-AC5AFCAF013F","ADE403B0-D7F2-4F11-8E56-AC5AFCAF013F"}
oDados:SetId(aData)
oDados:setDataItems({'regras_escrituracao'}) //obrigatorio
oDados:GetDataId() // opcional
cResponse := oDados:getAgregTypeByTax( , "000021") |
Exemplo Retorno
{
"data":{
"6D76CB61-2AEE-4F11-9E56-AC5AFCAF013F":{
"ICMSTG":{
"acao_tot_nf":"5",
"id_totvs":"000021"
}
},
"ADE403B0-D7F2-4F11-8E56-AC5AFCAF013F":{
"ICMSTG":{
"acao_tot_nf":"5",
"id_totvs":"000021"
}
}
} |
Libera os recursos utilizados pela instância da classe TCIWritten.
Utilização
aIds := {"369ca132-2b3b-ac96-6b78-3247afcc2219","a5dcda40-d145-28d1-c57f-1047e15ce1fe"}
cResponse := ""
oDados := TCIWritten():New()
oDados:SetId(aIds)
cResponse := oDados:GetDataId()
oDados:destroy() |
using NameSpace totvs.protheus.backoffice.fiscal.tciclass
Function Exemplo()
Local aData as array
Local cResponse as character
Local oDados as object
aData := {"ec451397-7b97-8114-a231-74a1490e1417"}
cResponse := ""
oDados := TCIWritten():New()
oDados:SetId( aData )
oDados:setDataItems({"regras_base", "regras_aliquota", "regras_escrituracao"})
cResponse := oDados:GetDataId()
Return cResponse |