Plugin de Integração ReceitaWS

Escopo Técnico - Comportamento

• Pelo tools, opção 3, o sistema realiza a criação das seguintes tabelas:
  • pluginintegracao
    • idpluginintegracao: long, pk
    • codigo: string, length: 10
    • idnativo: byte
    • codigoerp
    • wsversao
  • pluginintconfig
    • idpluginintconfig: long, pk
    • idpluginintegracao: long, fk
    • codigoelemento: varchar 20
    • agrupador: integer
    • sglcampo: string, length: 80
    • valor: string, length: 200
    • codigoerp
    • wsversao
  • pluginintvinculos
    • idpluginintvinculos: long, pk
    • idpluginintegracao: long, fk
    • idcondicaopagamento: long, fk
    • idtipolocal: long, fk
• Pelo tools, opção 3, o sistema realiza a criação da seguinte coluna na tabela pessoajuridica:
  • situacaocadastral: Varchar(80), nullable
  • situacaoespecial: Varchar(80), nullable
• Pelo tools, opção 5, é inserido registros na tabela wsconfigentidadecampo, segundo o script a seguir:

  • INSERT INTO public.wsconfigentidadecampo (nomecampo,idnpermitecadastrar,idnpermiteeditar,idnpermitevisualizar,idnobrigatorio,ordem,idwsconfigentidade,idnexiberelatorio)
    VALUES ('situacaocadastral',0,0,0,0,0,(select idwsconfigentidade from wsconfigentidade where nomeentidade = 'pessoajuridica'),0);
    INSERT INTO public.wsconfigentidadecampo (nomecampo,idnpermitecadastrar,idnpermiteeditar,idnpermitevisualizar,idnobrigatorio,ordem,idwsconfigentidade,idnexiberelatorio)
    VALUES ('situacaoespecial',0,0,0,0,0,(select idwsconfigentidade from wsconfigentidade where nomeentidade = 'pessoajuridica'),0); 
    INSERT INTO public.wsconfigentidadecampo (nomecampo,idnpermitecadastrar,idnpermiteeditar,idnpermitevisualizar,idnobrigatorio,ordem,idwsconfigentidade,idnexiberelatorio)
    VALUES ('unidadefederativa',0,0,0,0,0,(select idwsconfigentidade from wsconfigentidade where nomeentidade = 'local'),0);

  • Os registros inseridos na tabela wsconfigentidadecampo são implementados na tela Configuração > Cadastro > Cliente e na tela de cadastro de Cliente, aplicados respectivamente aos contextos referentes ao campo idwsconfigentidade.
• Pelo tools, opção 5, é inserido um registro na tabela "pluginintegracao" com código "receitaws".
• Ao clicar no botão configurar, o sistema abri tela de configuração com os seguintes elementos:
  • • Cabeçalho
      • Título do plugin
      • Link do manual de utilização: valor fixo https://tdn.totvs.com/pages/viewpage.action?pageId=733215521
    • Corpo da página
      • Label "Configurações do Pentaho"
        • "URL": campo de texto, para receber a URL em que a API do Pentaho (ferramenta de integração) estará sendo servido. (http://host:port)
        • "Usuário": campo de texto, para receber o usuário da autenticação básica do Pentaho
        • "Senha": campo de texto, com máscara de password, para receber a senha da autenticação básica do Pentaho
      • Label "Configurações da ReceitaWS"
        • "Token": Campo opcional para receber o token do plano pago
        • "Dias defasagem": Campo opcional para receber o número de dias que o sistema aceita que a API da ReceitaWS , no plano pago, responda com dados de seu banco interno. Caso a data do registro supere esse parâmetro, a ReceitaWS fará a requisição diretamente na API da receita federal, para trazer o dado em seu estado mais atual.
      • Label "Configurações do SFA"
        • "Timeout consulta": Campo numérico para receber o valor em segundos de quanto tempo a aplicação deve aguardar o retorno da API, antes de abortar a requisição e notificar o usuário: "O servidor da ReceitaWS não respondeu a tempo"
        • "Tipo local": Campo pesquisa, múltipla escolha, para receber valores de filtro de tipos de local que terão seus dados automaticamente preenchidos.
        • "Exibir botão buscar": Campo de opções fixas, com opções:
          • Adição: Opção que determinará que o botão de buscar dados na receita aparecerá no cadastro de um novo cliente
          • Edição: Opção que determinará que o botão de buscar dados na receita aparecerá na edição de um cliente cadastrado
          • Adição e Edição: Opção que determinará que o botão de buscar dados na receita aparecerá no cadastro de um novo cliente e na edição de um cliente cadastrado
        • Label "Mapeamento de campos" 
          • Grid segundo o modelo:

            • "Campo SFA": Registros somente visualização, representando o campo do SFA que será populado	"Campo ReceitaWS": Registros somente visualização, representando o campo do retorno da API	"Situação": Campo editável com opções Ativo/Inativo, checkbox
              parceiro.nomeparceiro	nome	Ativo
              parceiro.nomeparceirofantasia	fantasia	Ativo
              parceiro.cnae	atividade_principal // "{code}:{text}"	Ativo
              pessoajuridica.datafundacao	abertura	Ativo
              pessoajuridica.valorcapitalsocial	capital_social	Ativo
              pessoajuridica.situacaocadastral	situacao	Ativo
              pessoajuridica.situacaoespecial	situacao_especial	Ativo
              local.descricao	tipo	Ativo
              local.numero	numero	Ativo
              local.logradouro	logradouro	Ativo
              local.bairro	bairro	Ativo
              local.complemento	complemento	Ativo
              local.cep	cep	Ativo
              local.telefone	telefone // Se houver mais de um telefone, realizar a persistência de N registros, realizando o split pelo caracter "/"	Ativo
              local.email	email	Ativo
              local.cidade	municipio // select idcidade from cidade where upper(descricao) = upper(:municipio) and idunidadefederativa = (select idunidadefederativa from unidadefederativa where upper(sigla) = upper(:uf))	Ativo
              local.unidadefederativa	uf // select idunidadefederativa from unidadefederativa where upper(sigla) = upper(:uf)	Ativo

        • Label "Comportamento por situação"

          • Grid segundo o modelo:

            • No cabeçalho da grid deverá ter função "adicionar" para ter possibilidade de cadastrar-se múltiplos registros
              Situação cadastral	Situação especial	Comportamento
              Campo texto, editável O campo servirá para definir qual o código da propriedade "situacao" que definirá o comportamento do cadastro pelo campo "Lógica"	Campo texto, editável O campo servirá para definir qual o código da propriedade "situacao_especial" que definirá o comportamento do cadastro pelo campo "Lógica"	Campo de seleção fixa, com opções: Não permitir finalização Permitir finalização, gerando aprovação

  • Os valores são persistidos na entidadePluginIntConfig, utilizando a lógica do exemplo a seguir:

    • Se em tela, o usuário tiver preenchido os registros:

      • Situação cadastral	Situação especial	Comportamento
        ok	bloqueado	APR
        inativo		BLQ

    • O sistema realiza a persistência segundo a lógica:

      • codigoelemento (varchar20)	agrupador (integer)	sglcampo (varchar80)	valor (varchar200)
        comportamento	1	situacaocadastral	ok
        comportamento	1	situacaoespecial	bloqueado
        comportamento	1	comportamento	APR
        comportamento	2	situacaocadastral	INATIVO
        comportamento	2	comportamento	BLQ

  • Para campos que vinculam entidades fortes do SFA, o sistema deve persistir na tabela PluginIntVinculos, contendo as FKs das tabelas de retaguarda do SFA.

Requisição de dados no cadastro de clientes

• Se o plugin de integração "ReceitaWS" estiver ativo na tela Configuração > Integração > Plugins,
  • O sistema exibe o botão "Buscar" ao lado do campo CNPJ disponibilizado em contexto de Parceiro e Local
    • A exibição do botão deverá ser condicionada ao valor selecionado no campo "Exibir botão buscar".
    • Ao clicar no botão,
      • o sistema dispara uma requisição HTTP REST, sendo:
        • URL: ${Campo do plugin "Configurações do Pentaho"."URL"}/kettle/executeJob/?rep=COMMON_SERVICES&job=COMMONS_Bloco_ReceitaWS&CNPJ=${Valor do campo CNPJ preenchido em tela}
        • Autenticação: Basic
          • Usuário: Campo do plugin "Configurações do Pentaho"."Usuário"
          • Senha: Campo do plugin "Configurações do Pentaho"."Senha"
        • O sistema exibe Timer baseado no campo "Configurações do SFA"."Timeout consulta"
      • O serviço de integração (Pentaho), deverá consultar o campo "Configurações da ReceitaWS"."Token" para decidir qual é o método de consulta.
        • Caso o campo Token não seja preenchido, o método consultado deverá ser o segundo a documentação https://developers.receitaws.com.br/#/operations/queryCNPJFree
        • Caso o campo Token seja preenchido, o método consultado deverá ser o segundo a documentação https://developers.receitaws.com.br/#/operations/queryCNPJ
          • Além do CNPJ, nessa rota será necessário fornecer os valores dos campos "Configurações da ReceitaWS"."Token" e "Configurações da ReceitaWS"."Dias defasagem".
      • Após o término da consulta,
        

        • O pentaho responderá com XML, contendo 2 Tags:

          • RETORNO: Valor textual contendo o JSON de retorno, quando o STATUS for 200 ou 201, ou seja, status de sucesso. Quando o status for diferente de 200 ou 201, o valor virá com o texto que deverá ser exibido como mensagem de retorno do erro.
          • STATUS: Valor inteiro, contendo o numero do STATUS da requisição HTTP.

        • Caso a resposta seja bem sucedida, o conteúdo do campo RETORNO terá o modelo conforme:

          •  Expandir origem

            {
                              "status": "OK",
                              "ultima_atualizacao": "2019-08-24T14:15:22Z",
                              "cnpj": "string",
                              "tipo": "MATRIZ",
                              "porte": "string",
                              "nome": "string",
                              "fantasia": "string",
                              "abertura": "string",
                              "atividade_principal": [
                                {
                                  "code": "string",
                                  "text": "string"
                                }
                              ],
                              "atividades_secundarias": [
                                {
                                  "code": "string",
                                  "text": "string"
                                }
                              ],
                              "natureza_juridica": "string",
                              "logradouro": "string",
                              "numero": "string",
                              "complemento": "string",
                              "cep": "string",
                              "bairro": "string",
                              "municipio": "string",
                              "uf": "string",
                              "email": "string",
                              "telefone": "string",
                              "efr": "string",
                              "situacao": "string",
                              "data_situacao": "string",
                              "motivo_situacao": "string",
                              "situacao_especial": "string",
                              "data_situacao_especial": "string",
                              "capital_social": "string",
                              "qsa": [
                                {
                                  "nome": "string",
                                  "qual": "string",
                                  "pais_origem": "string",
                                  "nome_rep_legal": "string",
                                  "qual_rep_legal": "string"
                                }
                              ],
                              "billing": {
                                "free": true,
                                "database": true
                              }
                            }
            

      • Em posse do retorno da requisição, o sistema deverá atualizar os valores dos campos referenciados pelo campo "Mapeamento de campos"."Campo SFA", com o conteúdo do retorno segundo o campo "Mapeamento de campos"."Campo ReceitaWS",
        • A atualização do valor deverá ser condicionada aos registros da grid de "Mapeamento de campos" que estiverem com a coluna "Situação" = "Ativo"
        • A atualização dos campos deverá acontecer mesmo que o a configuração do cadastro esteja definindo o campo do SFA como não editável
        • Para a edição de cadastros de clientes, o sistema deverá atualizar apenas os campos de locais vinculados aos tipos de locais selecionados no campo "Configurações do SFA"."Tipo local".
          • O botão "buscar" também somente deverá aparecer para os locais vinculados aos tipos de locais selecionados no campo "Configurações do SFA"."Tipo local"
        • Quando o conteúdo do campo do SFA já estiver preenchido, e o valor do conteúdo anterior for diferente do conteúdo novo da requisição, o sistema deverá notificá-lo através de dialog, seguindo o modelo a seguir:
          • "Os seguintes campos foram atualizados pelo retorno da Receita Federal:"
          • (Elemento de scroll)
            • Pessoa Juridica:
              • ${Label do campo}:
                • De ${Valor antigo}
                • Para ${Valor novo}
            • Tipo Local ${Descrição do tipo de local}:
              • ${Label do campo}:
                • De ${Valor antigo}
                • Para ${Valor novo}
          • Opção OK
        • Se o campo do cadastro estiver selecionado como inativo na tabela wsconfigentidadecampo
          • O valor do campo não será atualizado pela requisição e não aparecerá na mensagem de informação de atualização
        • Se o campo  cadastro estiver selecionado como ativo na tabela wsconfigentidadecampo, porém estiver configurado para não ser exibido em tela (idnpermitevisualizar)
          •  valor do campo será atualizado pela requisição, porém, não aparecerá na mensagem de informação de atualização

Lógica de comportamento do cadastro de clientes após requisição

• No cadastro de cliente, após a requisição de consulta de CNPJ na ReceitaWS, o sistema realiza a consulta de se o valor retornado nos campos "situacao" e "situacao_especial" estão respeitando as regras cadastradas na grid "Configurações do SFA"."Comportamento por situação", onde a o agrupador entre o registro deve ser a operação AND.
  • Caso encontre um registro sendo respeitado pela regra do cadastro do plugin, executar a lógica segundo os possíveis exemplos:

    • Situação cadastral	Situação especial	Comportamento
      ATIVO	BLOQUEADO	Permitir finalização, gerando aprovação
      BAIXADO		Não permitir finalização

      • No exemplo acima, para o primeiro registro, caso o campo "situacao"="ATIVO" e "situacao_especial"="BLOQUEADO",

        • O sistema informa o usuário via pop up a seguinte mensagem:
          • "O cliente possui situação cadastral ATIVO, desde ${retorno.data_situacao} com motivo: ${retorno.motivo_situacao} e situação especial BLOQUEADO, desde ${retorno_data_especial}.
            Por esse motivo, o cadastro será encaminhado para aprovação"
        • Ao finalizar o cadastro, o sistema atualiza o campo parceiro.idtiposituacaoaprovacao = (select idtiposituacaoaprovacao from tiposituacaoaprovacao where sgltiposituacaoaprovacao = "PD")
          • Essa lógica sobreporá o comportamento padrão, que é definido pelos parâmetros "sim3g.cliente.novo.tipoSituacaoAprovacaoPadrao" e "sim3g.cliente.edicao.tipoSituacaoAprovacaoPadrao"
      • No exemplo do segundo registro, caso o campo "situacao"="BAIXADO",
        • O sistema informa o usuário via pop up a seguinte mensagem:
          • "O cliente possui situação cadastral BAIXADO, desde ${retorno.data_situacao} com motivo: ${retorno.motivo_situacao}
            Por esse motivo, não será possível finalizar o cadastro com esse CNPJ"
          • Opção OK
        • Ao finalizar o cadastro, o sistema retorna validação de bloqueio (rollback), com mensagem: 
          • "O cliente possui situação cadastral BAIXADO, desde ${retorno.data_situacao} com motivo: ${retorno.motivo_situacao}
            Por esse motivo, não será possível finalizar o cadastro com esse CNPJ"
          • Opção OK
  • Caso contrário, o sistema segue o fluxo de cadastro padrão, permitindo a finalização, onde o comportamento de aprovação deverá ser definida pelos parâmetros "sim3g.cliente.novo.tipoSituacaoAprovacaoPadrao" e "sim3g.cliente.edicao.tipoSituacaoAprovacaoPadrao"