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:
| Propriedade | Descrição | Tipo | Obrigatório? | Observação |
|---|---|---|---|---|
| items | Array das marcações | Array | Sim | |
| items.codRelogioExtChave | Código Relógio | Caracter | Não | Preenchido com o código da empresa e do relógio, conforme cadastrado no programa PE0620, campo Relógio. Obrigatório ser informado quando a marcação for de refeitório. |
| items.codFuncMsa | Código do funcionário | Caracter | Sim | Preenchido com a matrícula do funcionário conforme cadastro no programa FP1500 |
| items.codNsr | Código NSR | Numérico | Sim | |
| items.codPisMsa | Código do PIS do Funcionário | Caracter | Sim | Obrigatório para marcações realizadas em dispositivos que atendem à portaria 1510. |
| items.datMarcacAces | Data da marcação | Caracter | Sim | |
| items.numHorarMarcacAces | Hora da marcação em segundos | Numérico | Sim | |
| items.codRep | Código do REP | Caracter | Não | Preenchido com o número informado no programa PE0620, campo Número REP |
| items.codUnidExtChave | Código da Unidade | Caracter | Sim | Preenchido com o código da empresa e estabelecimento. Ex.: "99;99" |
| items.codUsuarExtChave | Código do usuário | Caracter | Sim | Preenchido com o código da empresa, estabelecimento e matrícula. Ex.: "99;99;4" |
| items.codFuso | Fuso Horário | Caracter | Sim | Obrigatório para marcações realizadas em dispositivos que atendem à portaria 671. |
| items.codCPF | Código do CPF do Funcionário | Caracter | Sim | Obrigatório para marcações realizadas em dispositivos que atendem à portaria 671. |
| items.numVersLayout | Versão Layout Arquivo AFD | Numérico | Sim | Quando preenchido com o valor: 0 - marcações de refeitório 1 - marcações da portaria 1510 3 - marcações da portaria 671 |
| items.inscrEmp | CNPJ ou CPF do empregador | Decimal | Não | |
| items.codCCT | Código Convenção Coletiva | Decimal | Não | Preenchido com o valor vazio (branco), quando a marcação for originada de um REP da portaria antiga (1510 ou 1510 INMETRO). Preenchido com o valor do acordo coletivo, quando a marcação for originada de um REP A. Preenchido com o valor vazio (branco), quando a marcação for originada de um equipamento de controle de acesso em refeitório. Preenchido sem zeros a esquerda. |
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:
| 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 codUnidExtChave. | |
| 400 | 00006 | É obrigatório informar o campo codUsuarExtChave. | |
| 400 | 00006 | Campo 'codRelogioExtChave' no formato incorreto. Deve ser preenchido como texto e conter o código da empresa e do relógio no ERP. | |
| 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 'codUnidExtChave' no formato incorreto. Deve ser preenchido como texto e conter o código da empresa e do estabelecimento no ERP. | |
| 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 | Foi enviado marcações de um relógio que não está cadastrado 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:
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.
Aviso importante
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 |
| 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 |
| 9982 | Indica erro no campo de chave externa da unidade(codUnidExtChave), quando valor informado for branco ou vazio |
| 9981 | Indica erro no campo de chave externa da unidade(codUnidExtChave), quando os valores:
|
| 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