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 lidas e o total de batidas com e sem erros.
- 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 seguintes opções:
- Gerar log Detalhado
- Gerar log Técnico
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.
- Maiores informações sobre a configuração no PE0400 estão disponíveis no documento de referência:
Detalhamentos das mensagens dos logs
Mensagens do 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 |
Mensagens do 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 |