Plugin de integração para simulação de impostos Datasul API Nativa/ Protheus API Nativa/ Genérico

01. DADOS GERAIS

Produto:	TOTVS CRM Automação da Força de Vendas
Linha de Produto:	Linha TOTVS CRM SFA
Módulo:	Venda
Função:	Impostos
Ticket:
Requisito/Story/Issue:	DTSFAPD-2267 - Obtendo detalhes do item... STATUS

02. ESCOPO FUNCIONAL/TÉCNICO

1. Cadastro de dados de acesso do Pentaho Carte

Ao invés de todos os plugins conterem campos para "Dados de acesso ao Pentaho Carte", na tela de Configuração > Integração > Plugins de Integração:

O sistema deverá disponibilizar botão "Configurações gerais" no roda teto da tela, abrindo nova tela, com os campos:
- - O campo senha deverá ser tipado como "password" para não pemitir visualização direta da senha na tela.
- Pelo tools, opção 5, o sistema deverá inserir novo registro na tabela pluginintegracao de codigo "configgeral"
- A persistência dos valores da tela de Configurações gerais deverá acontecer na tabela pluginintconfig para esses campos, vinculado à registro da tabela pluginintegracao de código "configgeral"
- Os plugins existentes (ReceitaWS e TOTVS Pagamento instantâneo deverão ter os campos de "Configurações do Pentaho removidos" e precisarão de refatoração para buscar das "Configurações Gerais")

2. Criação de configuração do novo plugin "Simulação de impostos"

O sistema deverá disponibilizar novo plugin de nome "Simulação de impostos", com descrição "Simule impostos diretamente no pedido de venda para negociações mais precisas com seu cliente."
- O link para o manual do plugin será Manual - Plugin de Integração "Simulação de Impostos"
- Pelo tools, opção 18, o sistema deverá persistir novo registro na tabela pluginintegracao.codigo com valor = IMPOSTO
- Para funcionar corretamente, o cadastro das configurações do plugin de Imposto deve inserir na tabela pluginintconfig as seguintes informações:

- - - Campo de label "Modelo de simulação de impostos":
      - Opções fixas (pluginintconfig.valor):
        "Protheus APIs Nativas": valor "protheus"
        "Datasul APIs Nativas": valor "datasul"
        "Genérico": valor "generico"
      - Registro na tabela pluginintconfig:
        idpluginintegracao = ID da tabela pluginintegracao com codigo = IMPOSTO
        codigoelemento = IMPOSTO
        agrupador = 0
        sglcampo = IMPOSTO_MODELO
        idnativo = 0
        valor = Dependendo da seleção (PROTHEUS, DATASUL ou GENERICO)
    - Campo de label "URL de conexão": textual obrigatório
      - Registro na tabela pluginintconfig:
        idpluginintegracao = ID da tabela pluginintegracao com codigo = IMPOSTO
        codigoelemento = IMPOSTO
        agrupador = 0
        sglcampo = IMPOSTO_URL
        idnativo = 0
        valor = Valor inserido pelo usuário
    - Grupo de elementos de label "Autenticação"
      - Campo de label "Usuário": textual obrigatório
        Registro na tabela pluginintconfig:
        idpluginintegracao = ID da tabela pluginintegracao com codigo = IMPOSTO
        codigoelemento = IMPOSTO
        agrupador = 0
        sglcampo = IMPOSTO_USUARIO
        idnativo = 0
        valor = Valor inserido pelo usuário
      - Campo de label "Senha": textual, obrigatório, tipado como "password" para não pemitir visualização direta da senha na tela.
        Registro na tabela pluginintconfig:
        idpluginintegracao = ID da tabela pluginintegracao com codigo = IMPOSTO
        codigoelemento = IMPOSTO
        agrupador = 0
        sglcampo = IMPOSTO_SENHA
        idnativo = 0
        valor = Valor inserido pelo usuário
    - Campo de label "Timeout ao requisitar impostos (seg)": campo numérico, se não informado, adotar o padrão 30 segundos
      - Registro na tabela pluginintconfig:
        idpluginintegracao = ID da tabela pluginintegracao com codigo = IMPOSTO
        codigoelemento = IMPOSTO
        agrupador = 0
        sglcampo = IMPOSTO_TIMEOUT
        idnativo = 0
        valor = Valor inserido pelo usuário
    - Campo de label "Obrigar simulação de impostos para:": Checkbox, seleção opcional
      - Checkbox de label "Gravar pedido"
        Registro na tabela pluginintconfig:
        idpluginintegracao = ID da tabela pluginintegracao com codigo = IMPOSTO
        codigoelemento = IMPOSTO
        agrupador = 0
        sglcampo = IMPOSTO_OBRIGATORIO_AO_GRAVAR
        idnativo = 0
        valor = Valor 0 ou1
      - Checkbox de label "Finalizar pedido"
        Registro na tabela pluginintconfig:
        idpluginintegracao = ID da tabela pluginintegracao com codigo = IMPOSTO
        codigoelemento = IMPOSTO
        agrupador = 0
        sglcampo = IMPOSTO_OBRIGATORIO_AO_FINALIZAR
        idnativo = 0
        valor = Valor 0 ou1

3. Implementação no pedido

No pedido de venda, caso o plugin de integração de código "imposto" estiver ativo,
- O sistema deverá disponibilizar o botão de "Calcular impostos" Web e ícone no Android.
  - Como já acontece com o modelo "PLUGIN_WINTHOR" atualmente, o sistema deve gerenciar a exibição de icone colorido baseado na situação dos impostos:
    - Impostos não calculados: cor amarela
    - Impostos calculados: cor verde
      - Ao alterar dados dos produtos, o ícone deve retornar para o status de "não calculado"
  - Como já acontece com o modelo "PLUGIN_WINTHOR", o pedido fará o aproveitamento dos impostos calculados para pedidos gravados através do campo pedidoproduto.idnimpostocalculado
    - As cores citadas acima também serão consequência do valor deste campo, onde todos os produtos marcados com valor 1 indicam impostos calculados. Qualquer registro com valor 0 indica impostos não calculados.
      - Ao alterar qualquer campo editável do item, o sistema deverá zerar o campo pedidoproduto.idnimpostocalculado
  - Ao clicar no botão de "Calcular impostos"
    - O sistema deverá disparar uma requisição POST para carte do Pentaho:
    - Imagem de exemplo:

URL: ${"Configurações gerais"."Configurações do Pentaho"."URL"}/kettle/executeJob/
Autenticação básica:
- Usuário: ${"Configurações gerais"."Configurações do Pentaho"."Usuário"}
- Senha: ${"Configurações gerais"."Configurações do Pentaho"."Senha"}
Content Type: application/x-www-form-urlencoded

Parametros:

rep=COMMON_SERVICES
job=COMMONS_Bloco_TAXSIMULATION

body=

{
    "idusuario": 1, //pedido.idusuarioprofissional
    "idparceiro": 1, //pedido.idparceiro
    "idlocal": 2, //pedido.idlocal
    "idlocalcobranca": 3, //pedido.idlocalcobranca
    "idfilialvenda": 3, //pedido.idlocalfilialvenda
    "idfilialretira": 4, //pedido.idlocalfilialretirada
    "idfilialfaturamento": 5, //pedido.idlocalfilialfaturamento
    "idtipopedido": 4, //pedido.idtipopedido
    "idtipocobranca": 5, //pedido.idtipocobranca
    "idtabelapreco": 6, //pedido.idtabelapreco
    "idcondicaopagamento": 5, //pedido.idcondicaopagamento
    "idsegmento": 8, //pedido.idsegmento
    "idtipologia": 8, //pedido.idtipologia
    "idoperacao": 8, //pedido.idoperacao
    "idmoeda": 8, //pedido.idindexador
    "idtipoestoque": 8, //pedido.idtipoestoque
    "valortotalbruto": 8.00, //Campo "Valor total bruto do resumo"
    "valortotalliquido": 9.00,//Campo "Valor total liquido do resumo"
    "descontopedido": [
        {
            "codigo": "8", //pedidotipodesconto.idtipodesconto > tipodesconto.codigo
            "percentual": 9.00, //pedidotipodesconto.percentual
            "valor": 10.00 //pedidotipodesconto.valor
        },
        {
            "codigo": "8", //pedidotipodesconto.idtipodesconto > tipodesconto.codigo
            "percentual": 9.00, //pedidotipodesconto.percentual
            "valor": 10.00 //pedidotipodesconto.valor
        }
    ],
    "pedidoproduto": [
        {
            "ordem": 1, //pedidoproduto.ordem
            "idproduto": 8, //pedidoproduto.idproduto
			"idembalagem": 10, //pedidoproduto.idembalagem,
            "quantidade": 9.00, //pedidoproduto.quantidade
            "precovenda": 10.00, //pedidoproduto.precovenda PS:Valor unitário
            "precotabela": 11.00, //pedidoproduto.precotabela PS:Valor unitário
            "precooriginal": 12.00, //pedidoproduto.precooriginal PS:Valor unitário
            "percentualdesconto": 13.00, //pedidoproduto.percentualdesconto
            "valordesconto": 13.00, //pedidoproduto.valordesconto PS:Valor unitário
            "percentualacrescimo": 13.00, //pedidoproduto.percentualacrescimo
            "valoracrescimo": 13.00, //pedidoproduto.valoracrescimo PS:Valor unitário
            "idtipopedido": 13.00, //pedidoproduto.idtipopedido
            "idtipoestoque": 14, //pedidoproduto.idtipoestoque
            "idtabelapreco": 15, //pedidoproduto.idtabelapreco
        },
        {
            "ordem": 1, //pedidoproduto.ordem
            "idproduto": 8, //pedidoproduto.idproduto
 			"idembalagem": 10, //pedidoproduto.idembalagem,
            "quantidade": 9.00, //pedidoproduto.quantidade
            "precovenda": 10.00, //pedidoproduto.precovenda PS:Valor unitário
            "precotabela": 11.00, //pedidoproduto.precotabela PS:Valor unitário
            "precooriginal": 12.00, //pedidoproduto.precooriginal PS:Valor unitário
            "percentualdesconto": 13.00, //pedidoproduto.percentualdesconto
            "valordesconto": 13.00, //pedidoproduto.valordesconto PS:Valor unitário
            "percentualacrescimo": 13.00, //pedidoproduto.percentualacrescimo
            "valoracrescimo": 13.00, //pedidoproduto.valoracrescimo PS:Valor unitário
            "idtipopedido": 13.00, //pedidoproduto.idtipopedido
            "idtipoestoque": 14, //pedidoproduto.idtipoestoque
            "idtabelapreco": 15, //pedidoproduto.idtabelapreco
        }
    ],
    "pedidoentrega": [
        {
            "idtipofrete": 4, //pedidoentrega.idtipofrete
            "idtransportadora": 7,//pedidoentrega.idparceirotransportador
			"idparceiroentrega": 8, //pedidoentrega.idparceiroentrega
            "valorfrete": 5.00, //pedidoentrega.valorfrete
            "valordespesa": 6.00, //pedidoentrega.valordespesa
            "valorseguro": 7.00 //pedidoentrega.valorseguro        
        },
        {
            "idtipofrete": 4, //pedidoentrega.idtipofrete
            "idtransportadora": 7,//pedidoentrega.idparceirotransportador
			"idparceiroentrega": 8, //pedidoentrega.idparceiroentrega
            "valorfrete": 5.00, //pedidoentrega.valorfrete
            "valordespesa": 6.00, //pedidoentrega.valordespesa
            "valorseguro": 7.00 //pedidoentrega.valorseguro        
        }
    ]
}

O retorno esperado virá com o modelo a seguir:

{
  "valortotalcomimpostos": 178.56,
  "valortotalimpostos": 21.96,
  "valortotaldespesa": 0, //pedidoentrega.valordespesa
  "valortotalseguro": 7, //pedidoentrega.valorseguro  
  "pedidoimposto": [
    {
      "sglimposto": "ICMS",
      "aliquota": 7,
      "valortotalimposto": 12.14
    },
    {
      "sglimposto": "IPI",
      "aliquota": 6,
      "valortotalimposto": 9.82
    }
  ],
  "itemimposto": [
    {
      "ordem": 1, //pedidoproduto.ordem
      "idproduto": 8, //pedidoproduto.idproduto 
	  "idproduto_externalid": "ABC" //pedpedidoproduto.idproduto > produto.codigoerp
      "valortotalcomimpostos": 89.21, //NÃO UNITÁRIO, precisa ser múltiplicado pela requisição.quantidade
      "valortotalfrete": 2.5, //NÃO UNITÁRIO, precisa ser múltiplicado pela requisição.quantidade
      "impostos": [
        {
          "sglimposto": "ICMS",
          "valorbase": 78.3,
          "aliquota": 6.24,
          "valortotalimposto": 6.24 //NÃO UNITÁRIO, precisa ser múltiplicado pela requisição.quantidade
        },
        {
          "sglimposto": "IPI",
          "valorbase": 78.3,
          "aliquota": 6,
          "valortotalimposto": 4.91 //NÃO UNITÁRIO, precisa ser múltiplicado pela requisição.quantidade
        },
        {
          "sglimposto": "ST",
          "valorbase": 78.3,
          "aliquota": 0,
          "valortotalimposto": 0 //NÃO UNITÁRIO, precisa ser múltiplicado pela requisição.quantidade
        },
        {
          "sglimposto": "COFINS",
          "valorbase": 78.3,
          "aliquota": 0,
          "valortotalimposto": 0 //NÃO UNITÁRIO, precisa ser múltiplicado pela requisição.quantidade
        },
        {
          "sglimposto": "CSLL",
          "valorbase": 78.3,
          "aliquota": 0,
          "valortotalimposto": 0 //NÃO UNITÁRIO, precisa ser múltiplicado pela requisição.quantidade
        }
      ]
    },
    {
      "ordem": 2, //pedidoproduto.ordem
      "idproduto": 9, //pedidoproduto.idproduto //
      "valortotalcomimpostos": 84.3, //NÃO UNITÁRIO, precisa ser múltiplicado pela requisição.quantidade
      "valortotalfrete": 2.5, //NÃO UNITÁRIO, precisa ser múltiplicado pela requisição.quantidade
      "impostos": [
        {
          "sglimposto": "ICMS",
          "valorbase": 78.3,
          "aliquota": 5.9,
          "valortotalimposto": 5.9 //NÃO UNITÁRIO, precisa ser múltiplicado pela requisição.quantidade
        },
        {
          "sglimposto": "IPI",
          "valorbase": 78.3,
          "aliquota": 6,
          "valortotalimposto": 4.91 //NÃO UNITÁRIO, precisa ser múltiplicado pela requisição.quantidade
        },
        {
          "sglimposto": "ST",
          "valorbase": 78.3,
          "aliquota": 0,
          "valortotalimposto": 0 //NÃO UNITÁRIO, precisa ser múltiplicado pela requisição.quantidade
        },
        {
          "sglimposto": "COFINS",
          "valorbase": 78.3,
          "aliquota": 0,
          "valortotalimposto": 0 //NÃO UNITÁRIO, precisa ser múltiplicado pela requisição.quantidade
        },
        {
          "sglimposto": "CSLL",
          "valorbase": 78.3,
          "aliquota": 0,
          "valortotalimposto": 0 //NÃO UNITÁRIO, precisa ser múltiplicado pela requisição.quantidade
        }
      ]
    }
  ]
}

Com o retorno acima, o sistema deverá persistir as informações em tela, segundo o seguinte de-para:

Retorno da Simulação	Campo do SFA
itemimposto.impostos.sglimposto	pedidoimposto.idimposto
itemimposto.impostos.valorbase	pedidoimposto.valorbasecalculoreducao
itemimposto.impostos.aliquota	pedidoimposto.valorbasecalculo
itemimposto.impostos.valortotalimposto	pedidoimposto.valorimposto
itemimposto.ordem / itemimposto.idproduto	pedidoimposto.idpedidoproduto (procurar por pedidoproduto.ordem e pedidoproduto.idproduto respectivamente)
itemimposto.valortotalfrete	pedidoproduto.valorfrete
itemimposto.valortotalcomimpostos	pedidoproduto.valortotalcomimpostos

Para a devida identificação do produto no retorno, o sistema deverá considerar a seguinte lógica:
- Caso seja enviada a propriedade "idproduto" diferente de nulo/vazio, o sistema deve considerá-la para a identificação do produto referenciado na tela.
- Caso contrário,
  - O sistema deve considerar a propriedade "idproduto_externalid", de forma que a identificação do idproduto deve acontecer pela seguinte consulta:
    - /* select idproduto from produto where codigoerp = :idproduto_externalid
A representação dos impostos em tela seguirá o modelo atual, exibindo os valores persistidos na linha do item e nos resumos, agrupando os valores dos itens.

Ao gravar o pedido,
- Caso a checkbox "Gravar pedido" estiver marcada, o sistema deverá restringir a gravação caso os impostos não estiverem calculados (cor verde), com mensagem: "É obrigatória a simulação de impostos para executar esta ação"
Ao finalizar o pedido
- Caso a checkbox "Finalizar pedido" estiver marcada, o sistema deverá restringir a finalização caso os impostos não estiverem calculados (cor verde), com mensagem: "É obrigatória a simulação de impostos para executar esta ação"

PS: É importante que tanto a requisição, quanto o retorno sejam logadas no console (f12) e log (server.log) da Web/Wildfly, para facilitar triagem de chamados envolvendo simulação de impostos.

4. Modelo de requisição para simulação de impostos Protheus APIs Nativas

O Pentaho Carte, recebendo a requisição da aplicação na rota COMMONS_Bloco_TAXSIMULATION, deverá tratar os dados recebidos segundo o modelo da entrada da API de simulação de impostos do Protheus, segundo documentação https://api.totvs.com.br/apidetails/SalesTaxes_v1_000.json

Com o retorno, o serviço de integração deverá ao menos implementar os campos definidos pela tabela de-para do ponto 3.

5. Modelo de requisição para Simulação de impostos Datasul APIs Nativas

O Pentaho Carte, recebendo a requisição da aplicação na rota COMMONS_Bloco_TAXSIMULATION, deverá tratar os dados recebidos segundo o modelo da entrada da API de simulação de impostos do Datasul, que segue o mesmo modelo de body da documentação https://api.totvs.com.br/apidetails/SalesTaxes_v1_000.json

A URL da rota é definida pelo padrão; ${base_url}/api/ftp/v2/ItemTaxSimulationPublic

Com o retorno, o serviço de integração deverá ao menos implementar os campos definidos pela tabela de-para do ponto 3.

6. Modelo de requisição para simulação de impostos Genérica

Será implementado um modelo genérico padrão, onde o Pentaho deverá enviar requisição com autenticação básica definida segundo modelo padrão e esperando receber retorno segundo modelo padrão definido pela documentação Manual - Plugin de Integração "Simulação de Impostos".

Caso os sistemas terceiros se adaptem ao modelo padrão definido acima, o requisito de simulação de impostos poderá ser implementados sem necessidade de customização.

Entretanto, caso os sistemas não possam se adaptar para receber e retornar a requisição segundo o definido pela documentação acima, esse modelo de simulação de impostos será configurado na aplicação para que dispare serviço de integração customizado, que respeita apenas o contrato requisição/retorno definido entre aplicação/pentaho.

Árvore de páginas