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 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.

Parâmetros e Chamada do Método:

Autenticação do tipo básica. 

{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"
                    }

                 ]
}

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."
                   }
                 ]
}

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.