INTEGRAÇÃO

Contexto de Negócio (Introdução)

Atualmente a integração de marcações de ponto do Suricato para o TOTVS HCM ocorre através de uma conexão direta com o banco de dados, atualizando a tabela msa_control_marcac.

Há a necessidade de realizar esta integração através de uma API REST garantindo a integridade da informação e, evitando assim a necessidade de conexão direta com o banco de dados. 

Sistemas Envolvidos

• HCM (módulo Controle de Frequência): O módulo Controle de Frequência permite de forma prática, segura e automática o controle da apuração de informações referentes à frequência dos funcionários de uma empresa, possibilitando, também, o controle e o acompanhamento do consumo e cobrança de refeições dos funcionários, quando esta é feita em refeitório na empresa.

• Suricato (Telemática):  software multi-idioma para a gestão integrada da segurança e controle de acesso.

Pré-requisitos instalação/implantação/utilização

• Versões mínima do TOTVS/Datasul: 12.1.34
• Servidor de aplicação tomcat (não é compatível com o servidor de aplicação jboss)
• Estrutura de rede estável, para que haja trafego de dados sem interrupção.
• Datasul devidamente configurado e serviço Rest habilitado em seu server, com acesso à internet.

Integração

O objetivo desta integração é permitir a integração das marcações de ponto do Suricato para o Datasul e, este efetue efetuar a validação e gravação das marcações na tabela marcac_nova_integr, sem que ocorra acesso direto ao banco de dados por parte do Suricato.

A API REST recordClockMarkings será consumida pelo Suricato e poderá receber no método POST os seguintes parâmetros:

Parâmetros e Chamada do Método:

Autenticação do tipo básica. 

Método POST.

{protocolo}://{host}/api/rh/v1/recordClockMarkings

A API REST recordClockMarkings será consumida pelo Suricato e poderá receber no método POST os seguintes parâmetros:

OBS:

* : obrigatório para marcações realizadas em dispositivos que atendem à portaria 1510.

**: obrigatório para marcações realizadas em dispositivos que atendem à portaria 671 ou, dispositivos que atendem a portaria 1510 e que geram a informação do CPF no campo PIS (primeira posição preenchida com 8 ou 9).

Request da API:

Exemplo: Marcação Portaria 1510

{
    "items": [
                       {
                         "codRelogioExtChave": "",
                         "codFuncMsa": "529",
                         "codNsr": 1,
                         "codPisMsa": "15423654711",
                         "datMarcacAces": "2021-10-21 09:30:00.000",
                         "numHorarMarcacAces": 34200,
                         "codRep": "5009940099846",
                         "codUnidExtChave": "10;1",
                         "codUsuarExtChave": "10;1;529"
                    },

                    {
                         "codRelogioExtChave": "",
                         "codFuncMsa": "1356",
                         "codNsr": 2,
                         "codPisMsa": "15423654711",
                         "datMarcacAces": "2021-10-23 22:00:00.999",
                         "numHorarMarcacAces": 79200,
                         "codRep": "5009940099846",
                         "codUnidExtChave": "10;1",
                         "codUsuarExtChave": "10;1"
                    }

                 ]
}

Dados utilizados da API

"S" para sim

"N" para não. 

Situações de Erros Tratados

O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros. Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.

Tratamento de erros de integração Datasul HCM:

Mensagens de Pré-Validação

Erro

Mensagem

Solução

265

Processo (nrProc) deve ser informado(a). 

Verificar se a propriedade json nrProc está preenchida no pacote enviado .

{
   			"message": "Processo (nrProc) deve ser informado(a).\n",
    		"code": "265",
    		"type": "error"
}

Informe um(a) Tipo Processo (tpProc) válido(a). Valores Válidos: 1 ou 2 ou 3

{
   			"message": "Informe um(a) Tipo Processo (tpProc) válido(a). Valores Válidos: 1 ou 2 ou 3.\n",
    		"code": "158",
            "type": "error"
}

Processo cadastrado(a) no HCM deve ser mantido neste produto. Verifique o FP0030.

{
   			"message": "Processo cadastrado(a) no HCM deve ser mantido neste produto. Verifique o FP0030.\n",
    		"code": "56650",
            "type": "error"
}

Empresa não relacionada com Nenhum Empregador.

{
   			"message": "Empresa não relacionada com Nenhum Empregador",
    		"code": "7137",
            "type": "error"
}

Exemplo: Marcação Portaria 671

{
    "items": [
                {
                    "codRelogioExtChave": "",
                    "codFuncMsa": "4",
                    "codNsr": 1000,
                    "codCPF": "02709509903",
                    "codFuso": "-0300",
                    "numVersLayout": 3,
                    "inscrEmpr": "012457856000158",
                    "datMarcacAces": "2022-09-08 09:30:00.000",
                    "numHorarMarcacAces": 34200,
                    "codRep": "858585565656",
                    "codUnidExtChave": "99;99",
                    "codUsuarExtChave": "99;99;4"
                },
                {
                    "codRelogioExtChave": "",
                    "codFuncMsa": "4",
                    "codNsr": 1002,
                    "codCPF": "02709509903",
                    "datMarcacAces": "2022-09-08 22:00:00.999",
                    "numHorarMarcacAces": 79200,
                    "codFuso": "-0300",
                    "numVersLayout": 3,
                    "inscrEmpr": "012457856000158",
                    "datMarcacAces": "2022-09-08 09:30:00.000",
                    "codRep": "858585565656",
                    "codUnidExtChave": "99;99",
                    "codUsuarExtChave": "99;99;4"
                }

        ]
}

Situações de Erros Tratados

A API irá retornar a lista com o indicativo individual de sucesso ou erro na gravação. Os retornos possíveis estão na lista abaixo:

Exemplo de retorno da API recordClockMarkings:

{
    "items": [
                   {
                       "codRelogioExtChave": "",
                       "codFuncMsa": "529",
                       "codNsr": 1,
                       "codPisMsa": "17962727770",
                       "datMarcacAces": "2021-10-21 09:30:00.000",
                       "numHorarMarcacAces": 34200,
                       "codRep": "5009940099846",
                       "codUnidExtChave": "10;1",
                       "codUsuarExtChave": "10;1;529",
                       "status": 200,
                       "errorCode": "",
                       "message": "Marcação gravada com sucesso"
                   },
                   {
                       "codRelogioExtChave": "",
                       "codFuncMsa": "1356",
                       "codNsr": 2,
                       "codPisMsa": "10699643292",
                       "datMarcacAces": "2021-10-22 22:00:00.999",
                       "numHorarMarcacAces": 79200,
                       "codRep": "5009940099846",
                       "codUnidExtChave": "10;1",
                       "codUsuarExtChave": "10;1",
                       "status": 400,
                       "errorCode": "00006",
                       "message": "Campo 'codUsuarExtChave' no formato incorreto. Deve ser preenchido como texto e conter o código da empresa, do estabelecimento e matricula do funcionário no ERP."
                   }
                 ]
}

Dado Registro infoSusp (codSusp: 1) incorreto - indSusp (50).

{
   			"message": "Dado Registro infoSusp (codSusp: 1) incorreto - indSusp (50).",
    		"code": "53817",
            "type": "error"
}

OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma ou não estejam de acordo com o leiaute do eSocial. Vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.

Checklist de suporte da aplicação

Itens a serem verificados durante o atendimento:

• Verificar se os pré-requisitos foram atendidos para a chamada da API;
• Verificar se na chamada da API o EndPoint, o nome do serviço e todos os campos obrigatórios foram informados;
• Verificar se o retorno da API apresenta algum erro tratado (códigos e mensagens de erro citados neste documento) e consultar a solução na mesma tabela que descreve o erro;
• Em caso de Erro não tratado, verificar se possui alguma informação de banco de dados, conexão com o servidor, clientlog, log do appServer ou algo que possa identificar a origem do problema.

EMS2:

• Verificar se os parâmetros de conexão foram cadastrados corretamente no CD0387: URL, Porta, Usuário e Senha.
• Verificar se estão cadastrados corretamente os processos no CD2021 dentro do período selecionado no CD2014.
• Verificar se o processo (CD2021) está relacionado ao estabelecimento (CD2021A).