ER_PCREQ-10013_Validar_CEP_no_CRM_(HTML)_com_TOTVS_Mashups

Informações Gerais

   Legenda: 1 – Inovação 2 – Manutenção (Os demais campos devem ser preenchidos para ambos os processos). 

Objetivo

Permitir ao usuário consultar os dados referentes ao CEP na base dos Correios através da API do TOTVS Mashups. Esta consulta tem por intenção validar o CEP informado no cadastro dos endereço junto a base dos Correios a fim de garantir maior integridade. A utilização do TOTVS Mashups será opcional, sendo necessário ativa-la para utilização no CRM.

Definição da Regra de Negócio

Parâmetros

A fim de garantir a suavização das novas funcionalidades, o primeiro passo para este desenvolvimento é criar um novo parâmetro no CRM (MASHUPS_ATIVOS) para que seja possível chavear a funcionalidade. Este parâmetro tem como função habilitar e desabilitar as chamadas à API do TOTVS Mashups. 

IF NOT CAN-FIND(FIRST CRM_PARAM NO-LOCK WHERE CRM_PARAM.NOM_PARAM_CRM = 'MASHUPS_ATIVOS') THEN DO:
    CREATE CRM_PARAM.
    ASSIGN CRM_PARAM.NUM_ID = NEXT-VALUE(SEQ_CRM_PARAM).
           CRM_PARAM.NOM_GRP_PARAM = 'Integração'.
           CRM_PARAM.NOM_TIT_PARAM = 'Habilita a integração com o serviço do TOTVS Mashups?'.
           CRM_PARAM.NOM_PARAM_CRM = 'MASHUPS_ATIVOS'.
           CRM_PARAM.DSL_PARAM_CRM = 'false'.
           CRM_PARAM.DSL_PARAM_CRM_DEFAULT = 'false'.
           CRM_PARAM.IDI_CAMPO_COMPON = 4. 
           CRM_PARAM.IDI_TIP_DADOS_CRM = 2. 
          
 CRM_PARAM.DSL_DESCR_PARAM = 'Este parâmetro indica se o CRM está 
habilitado a utilizar os serviços de domínio público disponíveis no 
TOTVS Mashups (Consulta a base de CEP dos Correios, Receita Federal, 
entre outros). Para maiores informações entre em contato com o Suporte 
da TOTVS.'.
END.

Este parâmetro deve ser incluído no programa crm_param.p para que o administrador do CRM possa realizar a carga do mesmo no sistema. Por padrão este parâmetro será liberado como 'false', ou seja, esta funcionalidade estará desativada, sendo necessário ativa-la para utilização.

Validação de CEP

A consulta/validação do CEP através da API do TOTVS Mashups deverá ocorrer de forma transparente para o usuário final.

Desta forma será preciso alterar o a fachada de CEP (fchcrm1008.p) para adicionar um novo método para realizar este procedimento com a seguinte assinatura:

PROCEDURE validatePostalCode:
    
    DEFINE INPUT  PARAM c_code  AS CHARACTER  NO-UNDO.
    
    DEFINE OUTPUT PARAM DATASET FOR DSCRMCEP.
    DEFINE OUTPUT PARAM TABLE   FOR RowErrors.

END PROCEDURE.

Este método deverá estar exposto como serviço respeitando a seguinte assinatura:

PROCEDURE REST_GET_validate_postal_code:
    
    DEFINE INPUT  PARAM QP_code  AS CHARACTER  NO-UNDO.
    
    DEFINE OUTPUT PARAM DATASET FOR DSCRMCEP.
    DEFINE OUTPUT PARAM TABLE   FOR RowErrors.

    RUN validatePostalCode (INPUT QP_code, OUTPUT DATASET DSCRMCEP, OUTPUT TABLE RowErrors).

END PROCEDURE.

A implementação do método deverá seguir a seguinte linha:

• Verificar se o CRM está habilitado a utilizar a API do TOTVS Mashups através do parâmetro: MASHUPS_ATIVOS.
  
  
• Caso o CRM não esteja habilitado a utilizar a API do TOTVS Mashups, o sistema deve continuar realizando a consulta na base de CEP do próprio CRM através do método: findPostalCode.
  
  
• Com o CRM habilitado a utilizar a API do TOTVS Mashups, o sistema deve realizar a chamada ao serviço de consulta de CEP conforme documentação disponibilizada pelo Framework JOI aqui.
  
  
• Quando ocorrer algum problema com a chamada da API do TOTVS Mashups o sistema deverá realizar a consulta na base de CEP do próprio CRM através do método findPostalCode. E retornar uma mensagem de informação ao usuário de que não foi possível realizar a consulta na API do TOTVS Mashups e o erro deve ser impresso no arquivo de log do Progress Appserver. Mensagem: Ocorreu uma situação inesperada durante a chamada ao serviço do TOTVS Mashups. A verificação do CEP foi realizada na base do CRM.

Quando encontrado o CEP na API do TOTVS Mashup, o retorno se dará através de um 'objeto' com os seguintes atributos:

• CEP: código do CEP informado;
• Estado: Código da unidade de federação;
• Cidade: Nome da cidade;
• Bairro: Nome do bairro, quando existir;
• Endereço: Logradouro, quando existir.
  
  

Os dados retornados pela API do TOTVS Mashups para o CEP devem ser converitdos para os registros do CRM. Desta forma para cada um dos itens (Estado, Bairro e Cidade) será preciso buscar os respectivos registros na base do CRM conforme as seguintes regras:

• País: Buscar os dados na tabela crm_pais de acordo com o país padrão informado para o CRM;

• Estado: Buscar os dados na tabela crm_unid_federac utilizando como filtros o código interno do país (crm_pais.num_id) e o código da unidade de federação (nom_unid_federac);
  
  
• Cidade: Buscar os dados na tabela crm_cidad utilizando como filtros o código interno da unidade de federação (crm_unid_federac.num_id) e o nome da cidade (nom_cidade);
  
  
• Bairro: Buscar os dados na tabela crm_bairro utilizando como filtros o código interno da cidade (crm_cidad.num_id) e o nome do bairro (nom_bairro); Caso o bairro não seja encontrado no CRM deve retornar para a tela de cadastro de endereço apenas o nome do bairro retornado pela API do TOTVS Mashups, para que, posteriormente, na inclusão do endereço o bairro seja incluído no CRM.
  
  

Na parte HTML do CRM será preciso criar o método validatePostalCode na factory crm.crm_cep.factory (fchcrm1008.js), conforme exemplo a baixo:

factory.validatePostalCode = function (cep, callback) {
    return this.TOTVSQuery({method: 'validate_postal_code', code: cep}, function (result) {
        if (callback) {
            callback(result);
        }
    });
};

E por fim alterar o método getZipcodes no controller crm.account-address.edit.control (address-services.js) para realizar a chamada ao método validatePostalCode ao invés do findPostalCode, conforme exemplo:

this.getZipcodes = function(value) {

    this.postalcodes = undefined;

    if (!value || value === '' || value.length < 8) return [];

    return postalcodeFactory.validatePostalCode(value, function(result) {

        CRMControlAccountAddressEdit.postalcodes = result || [];

        if (CRMControlAccountAddressEdit.postalcodes.length === 0) {
            $rootScope.$broadcast(TOTVSEvent.showNotification, {
                type: 'warning',
                title: $rootScope.i18n('l-addresses', [], 'dts/crm'),
                detail: $rootScope.i18n('msg-not-found-postal-code', [
                    value
                ], 'dts/crm')
            });
        }
    });
}

Opcional

Protótipo de Tela

<Caso necessário inclua protótipos de telas com o objetivo de facilitar o entendimento do requisito, apresentar conceitos e funcionalidades do software>.

Protótipo 01

Dicionário de Dados

Arquivo ou Código do Script: AAA – Negociação Financeira / *Versao=CP.2014.12_03*/

Grupo de Perguntas

Nome: FINSRF2

(Opcional)

Consulta Padrão

<Informações utilizadas na linha Protheus>

Consulta: AMB

(Opcional)

Estrutura de Menu

<Informações utilizadas na linha Datasul>.

Procedimentos

Programas

Cadastro de Papéis

<O cadastro de papéis é obrigatório para os projetos de desenvolvimento FLEX a partir do Datasul 10>.

<Lembrete: o nome dos papeis em inglês descrito neste ponto do documento, devem ser homologados pela equipe de tradução>.