INTEGRAÇÃO

Contexto de Negócio (Introdução)

Há a necessidade de realizar a integração das marcações de ponto do Ahgora PontoWeb by TOTVS através da API REST recordClockMarkings, garantindo a integridade das informações em todo processamento realizado pelos programas do módulo Controle de Frequência. 

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.

• Ahgora PontoWeb by TOTVS:  software de ponto 100% digital para controle de jornada.

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

• Versões mínima do TOTVS/Datasul: 12.1.2411.15, 12.1.2503.10, 12.1.2507.4 ou superiores.
• Realizar a integração do cadastro de funcionários entre a Folha de Pagamento RH Datasul e o PontoWeb Ahgora. Para mais detalhes acessar a documentação Integração RH Datasul X Ahgora#1. 
• 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 da api recordClockMarkings é permitir a integração das marcações de ponto do Ahgora PontoWeb by TOTVS para o Datasul, e este efetuar a validação destas marcações, bem como realizar a gravação na tabela marcac_nova_integr.

Parâmetros e Chamada do Método:

Autenticação

A api recordClockMarkings utiliza Basic Authentication.

• • Para autenticação com o RH Datasul, basta ter um usuário cadastrado no sistema, e utilizar o Basic Authentication usuário e senha.
  • Sugerimos que seja um usuário genérico, para evitar recadastro caso ocorra alteração de permissões de usuário.

Endpoint

api/rh/v1/recordClockMarkings

Método

O método a ser utilizado é o POST.

Chamada do Médodo

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

A API REST recordClockMarkings será consumida pelo Ahgora PontoWeb by TOTVS e poderá receber os seguintes parâmetros:

Exemplos do Json de Request da API:

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:

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

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.

Logs da Integração de Marcações

Contexto

Os Logs para acompanhamento e análise do processo de integração de marcações estão divididos em dois tipos, que são:

• • Log Detalhado: são apresentadas informações sobre cada batida lida no momento em que ocorreu a integração, identificando se houveram erros, a descrição do erro, o total de batidas recebidas, o total de batidas com erros e o total de batidas integradas.
  • Log Técnico: são apresentadas informações técnicas da comunicação entre o Suricato e TOTVS Datasul por meio da API. Neste log é possível visualizar o json recebido, contendo os dados da marcação e a hora do evento.

Configuração dos Logs

A configuração dos Logs deve ser feita através do programa PE0400(Configurador de Logs Processos MPE), onde estão disponíveis as duas opções de log acima descritas para escolha, podendo desta forma gerar somente um deles, ou os dois ao mesmo tempo.

Quanto a frequência de geração dos logs, existem duas opções:

• • Por Execução da API,gera um arquivo a cada vez que ocorre a execução da api recordClockMarkings para integrar as marcações do Suricato para o TOTVS Datasul. O nome de cada arquivo contém a data e hora de sua criação para identificação.
  • Diária, gera um arquivo por dia em quanto a configuração estiver ativa. O nome de cada arquivo contém a data de sua criação.

  Os arquivos de log serão criados no diretório spool da sessão Progress do Servidor de Aplicação.

Maiores informações sobre a configuração no PE0400 estão disponíveis no documento de referência do Configurador de Logs Processos MPE. 

Detalhamentos das mensagens dos Logs

• Log detalhado

• Log técnico