Histórico da Página
| Índice |
|---|
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.
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:
| Informação Enviada pela API | Conteúdo da Marcação Enviada | Campo da Tabela marcac_nova_integr | Conteúdo Gravado no Campo |
|---|---|---|---|
| codFuncMsa | "80","125" | cod_func_msa | 80|125 |
| codUsuarExtChave | "10;1;80","10;1;125" | cod_usuar_ext_chave | 10;1;80|10;1;125 |
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:
| 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 |
| 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 | Array - Caracter | Sim | Preencher com a matrícula do funcionário. Usar como referência o codInterno enviado na integração do funcionário. Quando se tratar de múltiplo vínculo no mesmo estabelecimento deve ser preenchido com as matrículas do funcionário de cada vínculo no estabelecimento. |
| 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 |
| codUsuarExtChave | Chave externa do funcionário | Array - 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. Quando se tratar de múltiplo vínculo no mesmo estabelecimento deve ser preenchido o código da empresa , do estabelecimento e a matrícula do funcionário, separados por ";" de cada vínculo no estabelecimento. |
| 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". |
| inscrEmp | CNPJ ao qual o REP-P está vinculado | Caracter | Sim | Preencher somente com os números do CNPJ do estabelecimento ao qual o REP-P está relacionado. |
| 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:
| Deck of Cards | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
|
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
| Deck of Cards | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
|
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.
| Informações | ||
|---|---|---|
| ||
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:
|
| 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:
|
| 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:
|
| 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:
Esta condição é aplicada apenas para marcações com o número de REP (codRep) informado. O valor esperado correto é: 10;131516 |
| 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:
|
| 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 |
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas