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

• 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.1415, 12.1.2503.910, 12.1.2507.3 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 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 e gravação das marcações destas marcações, bem como realizar a gravação na tabela marcac_nova_integr.

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 Ahgora PontoWeb by TOTVS e poderá receber no método POST os seguintes parâmetros:

Preencher com o número do processo do último acordo ou convenção coletiva depositado. Caso não haja, informar
"99999999999999999".

Preencher somente com os números do CPF.

Preencher com a matrícula do funcionário. Usar como referência o codInterno enviado na integração do funcionário.

Preencher com a informação do fuso horário que consta na data e hora da marcação do ponto registrada no REP-P/REP-A. 

Formato da data e hora de marcação: "AAAA-MM-ddThh:mm:00ZZZZZ", onde:

ZZZZZ: fuso horário, onde o primeiro digito representa o sinal (positivo ou negativo) e os outros quatro dígitos representam a hora e os minutos.

Preencher com o NSR gerado pelo REP-P/REP-A quando ocorre o registro da marcação de ponto.

Preencher com a palavra "PONTOWEB".

Para REP-P: preencher com o número de registro no INPI.

Para REP-A: - preencher com o número do processo do último acordo ou convenção coletiva depositado. Caso não haja, informar
"99999999999999999".

Preencher com o código da empresa, do estabelecimento e aa matrícula do funcionário, separados por ";".

Usar como referência o codInterno enviado na integração do funcionário.

Preencher com a informação da data e hora da marcação do ponto registrada no REP-P/REP-A. 

Formato da data e hora de marcação: "AAAA-MM-ddThh:mm:00ZZZZZ".

Preencher com o valor "3" que indica que as marcações atendem ao layout da portaria 671

Quando no Ahgora PontoWeb by TOTVS houver cadastro de funcionários com múltiplos vínculos no mesmo estabelecimento, as marcações destes funcionários serão enviadas para o Datasul com as informações "codFuncMsa" e "codUsuarExtChave" de todos os vínculos existentes. Neste cenário, os campos marcac_nova_integr.cod_func_msa e marcac_nova_integr.cod_usuar_ext_chave serão atualizados com as informações de todos os vínculos, separados por "|".

Exemplo:

A api recebe a marcação abaixo, na qual constam os dois vínculos do CPF 15974125460: 80 e 125, ambos no estabelecimento 1.

{
    "items": [
                {
                    "codCPF": "15974125460",
                    "codFuso": "+0300",
                    "codNsr": "8500",
                    "codRelogioExtChave":"PONTOWEB",
                    "codRep": "12121212121212121",
                    "codFuncMsa": ["80","125"],
                    "codUsuarExtChave": ["10;1;80","10;1;125"],
                    "datMarcacAces": "2024-07-21T12:00:00.000",
                    "numHorarMarcacAces": 43200,
                    "numVersLayout": "3",
                    "inscrEmp":"77778888999944"
                }

                 ]

}

Na tabela marcac_nova_integr estas informações ficarão gravadas da seguinte maneira:

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:

Exemplo de retorno da API recordClockMarkings

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:

Verifique codCPF informado

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.

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.

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:

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

Maiores Mais 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