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.14, 12.1.2503.9, 12.1.2507.3 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:

Tipo de Autenticação

A api recordClockMarkings utiliza a Autenticação Básica, sendo necessário ter um usuário/senha cadastrado no Datasul.

URL

A url para executar a api é a seguinte: {protocolo}://{host}/api/rh/v1/recordClockMarkings

Método

O método a ser utilizado é o POST.

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

Propriedade	Descrição	Tipo	Obrigatório?	Observação
items	Array das marcações	Array	Sim	Nas linhas abaixo estão detalhadas as informações que devem ser envidas no array items.
codCCT	Código da convenção coletiva	Caracter	Não	Preencher com o número do processo do último acordo ou convenção coletiva depositado. Caso não haja, informar "99999999999999999".
codCPF	Número do CPF do funcionário	Caracter	Sim	Preencher somente com os números do CPF.
codFuncMsa	Número da matrícula do funcionário	Caracter	Sim	Preencher com a matrícula do funcionário. Usar como referência o codInterno enviado na integração do funcionário.
codFuso	Fuso horário	Caracter	Sim	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.
codNsr	Número sequencial de registro	Caracter	Sim	Preencher com o NSR gerado pelo REP-P/REP-A quando ocorre o registro da marcação de ponto.
codRelogioExtChave	Identifica a integração Ahgora	Caracter	Sim	Preencher com a palavra "PONTOWEB".
codRep	Código do REP	Caracter	Sim	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".
codUsuarExtChave	Chave externa do funcionário	Caracter	Sim	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.
datMarcacAces	Data da marcação	Caracter	Sim	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".
numHorarMarcacAces	Hora da marcação em segundos	Numérico	Sim	Preencher com a hora e minutos da marcação de ponto, convertidos para segundos.
numVersLayout	Versão do layout do arquivo AFD	Caracter	Sim	Preencher com o valor "3", que indica que a marcação atende ao layout da portaria 671.

Exemplos do Json de Request da API:

{
"items": [

                {
                    "codCPF": "88888888888",
                    "codFuncMsa": "1",
                    "codFuso": "+0300",
                    "codNsr": "120024",
                    "codRelogioExtChave":"PONTOWEB",
                    "codRep": "80008000800080008",
                    "codUsuarExtChave": "10;1;1",
                    "datMarcacAces": "2025-08-04T08:00:00.000",
                    "numHorarMarcacAces": 28800,
                    "numVersLayout": "3",
                    "codCCT": "80008000800080008"
                },
                {   "codCPF": "88888888888",
                    "codFuncMsa": "1",
                    "codFuso": "+0300",
                    "codNsr": "120025",
                    "codRelogioExtChave":"PONTOWEB",
                    "codRep": "80008000800080008",
                    "codUsuarExtChave": "10;1;1",
                    "datMarcacAces": "2025-08-04T16:00:00.000",
                    "numHorarMarcacAces": 57600,
                    "numVersLayout": "3",
                    "codCCT": "80008000800080008"
                }
        ]
}

{
"items": [

                {
                    "codCPF": "88888888888",
                    "codFuncMsa": "1",
                    "codFuso": "+0300",
                    "codNsr": "120024",
                    "codRelogioExtChave":"PONTOWEB",
                    "codRep": "77744455522211177",
                    "codUsuarExtChave": "10;1;1",
                    "datMarcacAces": "2025-08-04T08:00:00.000",
                    "numHorarMarcacAces": 28800,
                    "numVersLayout": "3"
                },
                {   "codCPF": "88888888888",
                    "codFuncMsa": "1",
                    "codFuso": "+0300",
                    "codNsr": "120025",
                    "codRelogioExtChave":"PONTOWEB",
                    "codRep": "77744455522211177",
                    "codUsuarExtChave": "10;1;1",
                    "datMarcacAces": "2025-08-04T16:00:00.000",
                    "numHorarMarcacAces": 57600,
                    "numVersLayout": "3"
                }
        ]
}

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:

status	errorCode	message	OBS
200		Marcação gravada com sucesso.
400	00001	PIS em formato inválido ou inexistente no cadastro.
400	00002	NSR duplicado. Número já foi importado na tabela marcac_nova_integr .
400	00003	NSR não foi informado e é obrigatório.
400	00006	É obrigatório informar o campo codRelogioExtChave.
400	00006	É obrigatório informar o campo codFuncMsa.
400	00006	É obrigatório informar o campo codPisMsa.	Somente quando não estiverem informados os campos: codPisMsa e codCPF
400	00006	É obrigatório informar o campo datMarcacAces.
400	00006	É obrigatório informar o campo numHorarMarcacAces.
400	00006	É obrigatório informar o campo codRep.
400	00006	É obrigatório informar o campo codUsuarExtChave.
400	00006	Campo 'codNsr' no formato incorreto. Deve ser preenchido como numérico.
400	00006	Campo 'numHorarMarcacAces' no formato incorreto. Deve ser preenchido como numérico.
400	00006	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.
400	00006	Verifique codCPF informado	Somente quando o campo codCPF estiver informado e seu dígito verificador estiver incorreto.

Exemplo de retorno da API recordClockMarkings:

{
"items": [

                {
                    "codCPF": "88888888888",
                    "codFuncMsa": "1",
                    "codFuso": "+0300",
                    "codNsr": "120024",
                    "codRelogioExtChave":"PONTOWEB",
                    "codRep": "80008000800080008",
                    "codUsuarExtChave": "10;1;1",
                    "datMarcacAces": "2025-08-04T08:00:00.000",
                    "numHorarMarcacAces": 28800,
                    "numVersLayout": "3",
                    "codCCT": "80008000800080008"
                },
                {   "codCPF": "88888888888",
                    "codFuncMsa": "1",
                    "codFuso": "+0300",
                    "codNsr": "120025",
                    "codRelogioExtChave":"PONTOWEB",
                    "codRep": "80008000800080008",
                    "codUsuarExtChave": "10;1;1",
                    "datMarcacAces": "2025-08-04T16:00:00.000",
                    "numHorarMarcacAces": 57600,
                    "numVersLayout": "3",
                    "codCCT": "80008000800080008"
                }
        ]
}

{
"items": [
{
"codRelogioExtChave": "",
"codFuncMsa": "529",
"codNsr": 1,
"codCPF": "02709509903",
"datMarcacAces": "2021-10-21 09:30:00.000",
"numHorarMarcacAces": 34200,
"codRep": "5009940099846",
"codUnidExtChave": "10;1",
"codUsuarExtChave": "10;1;529",
"status": 200,
"errorCode": "",
"codCCT":"19269592961497986",
"message": "Marcação gravada com sucesso"
},
{
"codRelogioExtChave": "",
"codFuncMsa": "1356",
"codNsr": 2,
"codCPF": "02709509903",
"datMarcacAces": "2021-10-22 22:00:00.999",
"numHorarMarcacAces": 79200,
"codRep": "5009940099846",
"codUnidExtChave": "10;1",
"codUsuarExtChave": "10;1",
"status": 400,
"errorCode": "00006",
"codCCT":"19269592961497986",
"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.

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.

Não é recomendada a geração contínua destes logs, pois, podem causar problemas de espaço em disco.

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

Código	Detalhamento
9999	Indica início da execução do programa que grava as marcações em uma tabela intermediária (marcac_nova_integr) no TOTVS Datasul
9998	Indica início da leitura e baixa de marcações
9997	Indica a quantidade de marcações recebidas
9996	Indica erro ao tentar baixar uma marcação
9995	Indica erro quando o valor está em branco ou zero no campo data da marcação (datMarcacAces)
9994	Indica que o campo do PIS do funcionário (codPisMsa), está com erro pelos seguintes motivos: quantidade de caracteres informados no PIS maior que 12 funcionário está desligado na data da marcação
9993	Indica erro no campo CPF do funcionário (codCPF), com valor informado inválido
9992	Indica erro no campo NSR (codNsr), quando informado caracteres diferentes de números
9991	Indica erro no campo NSR (codNsr), quando o valor for zero
9990	Indica erro de duplicidade de marcação, quando utilizada a identificação por PIS do funcionário, considerando como critério de identificação os campos: NSR (codnsr) Código de REP (codRep) PIS (codPisMsa)
9989	Indica erro de duplicidade de marcação, quando utilizada a identificação por CPF do funcionário, considerando como critério de identificação os campos: NSR (codnsr) Código de REP (codRep) CPF (codCPF)
9988	Indica erro no campo NSR(codNsr), quando o valor informado está em branco ou com zero. Esta condição é aplicada apenas para marcações com o número de REP (codRep) informado.
9987	Indica erro no valor do campo chave externa do relógio (codRelogioExtChave), quando valor informado for branco. Esta condição é validada apenas para marcações que não contém o número de REP (codRep) informado.
9986	Indica erro no valor do campo chave externa do relógio(codRelogioExtChave) quando os valores: informados forem mais de dois quando o primeiro valor estiver em branco quando o segundo valor estiver em branco Esta condição é aplicada apenas para marcações com o número de REP (codRep) informado. O valor esperado correto é: 10;131516
9985	Indica erro no campo de chave externa do relógio(codRelogioExtChave), quando os valores informados do código da empresa e código do relógio não foram encontrado no cadastro de relógios FP0620 - Manutenção Relógio Ponto
9984	Indica erro no campo de hora da marcação(numHorarMarcacAces), quando o valor informado não é do tipo numérico
9983	Indica erro no campo de hora da marcação(numHorarMarcacAces), quando o valor informado for branco ou vazio
9980	Indica erro no campo de chave externa do usuário(codUsuarExtChave), quando o valor informado for branco ou vazio
9979	Indica erro no campo de chave externa do usuário(codUsuarExtChave), quando os valores: informados forem mais de três quando o só primeiro valor estiver em branco quando o só segundo valor estiver em branco quando o só terceiro valor estiver em branco
9978	Indica erro no campo de código do funcionário(codFuncMsa), quando o valor informado for branco ou vazio
9977	Indica erro ao não encontrar um funcionário, com código da empresa, código do estabelecimento e código do funcionário informado no campo chave externa do usuário (codUsuarExtChave)
9976	Indica uma marcação integrada com sucesso, informando os dados da marcação
9975	Informa o total de marcações integradas com sucesso
9974	Informa o total de marcações que não foram integradas
9973	Indica o término da baixa de marcações
9972	Indica o término da execução do programa de baixa de marcações

Log técnico

Código	Detalhamento
9899	Indica o início da execução da api apiRecordClockMarkings
9898	Indica o recebimento do json e faz a impressão no arquivo de log. Apresenta o cabeçalho de requisição, atributo e valores do json
9897	Indica o término do recebimento do json
9896	Indica o término da execução da api