Índice

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:

Expandir

title	Marcações Portaria 1510

{
"items": [
{
"codRelogioExtChave": "",
"codFuncMsa": "529",
"codNsr": 1,
"codCPF:"",
"codPisMsa": "15423654711",
"datMarcacAces": "2021-10-21 09:30:00.000",
"numHorarMarcacAces": 34200,
"codRep": "5009940099846",
"codUnidExtChave": "10;1",
"codUsuarExtChave": "10;1;529",
"codCCT":""
},

{
"codRelogioExtChave": "",
"codFuncMsa": "1356",
"codNsr": 2,
"codCPF:"",
"codPisMsa": "15423654711",
"datMarcacAces": "2021-10-23 22:00:00.999",
"numHorarMarcacAces": 79200,
"codRep": "5009940099846",
"codUnidExtChave": "10;1",
"codUsuarExtChave": "10;1",
"codCCT":""
}

]
}

Expandir

title	Marcação Portaria 671 REP-A

{
"items": [
{
"codRelogioExtChave": "",
"codFuncMsa": "4",
"codNsr": 1000,
"codCPF": "02709509903",
"codFuso": "-0300",
"numVersLayout": 3,
"inscrEmpr": "012457856000158",
"datMarcacAces": "2022-09-08 09:30:00.000",
"numHorarMarcacAces": 34200,
"codRep": "858585565656",
"codUnidExtChave": "99;99",
"codUsuarExtChave": "99;99;4",
"codCCT": "19269592961497986"

},
{
"codRelogioExtChave": "",
"codFuncMsa": "4",
"codNsr": 1002,
"codCPF": "02709509903",
"datMarcacAces": "2022-09-08 22:00:00.999",
"numHorarMarcacAces": 79200,
"codFuso": "-0300",
"numVersLayout": 3,
"inscrEmpr": "012457856000158",
"datMarcacAces": "2022-09-08 09:30:00.000",
"codRep": "858585565656",
"codUnidExtChave": "99;99",
"codUsuarExtChave": "99;99;4"
"codCCT": "19269592961497986"
}

]
}

Expandir

title	Marcação Portaria 671 REP-C

{
"items": [
{
"codRelogioExtChave": "",
"codFuncMsa": "4",
"codNsr": 1000,
"codCPF": "02709509903",
"codFuso": "-0300",
"numVersLayout": 3,
"inscrEmpr": "012457856000158",
"datMarcacAces": "2022-09-08 09:30:00.000",
"numHorarMarcacAces": 34200,
"codRep": "858585565656",
"codUnidExtChave": "99;99",
"codUsuarExtChave": "99;99;4",
"codCCT": ""

},
{
"codRelogioExtChave": "",
"codFuncMsa": "4",
"codNsr": 1002,
"codCPF": "02709509903",
"datMarcacAces": "2022-09-08 22:00:00.999",
"numHorarMarcacAces": 79200,
"codFuso": "-0300",
"numVersLayout": 3,
"inscrEmpr": "012457856000158",
"datMarcacAces": "2022-09-08 09:30:00.000",
"codRep": "858585565656",
"codUnidExtChave": "99;99",
"codUsuarExtChave": "99;99;4"
"codCCT": ""
}

]
}

Expandir

title	Refeitório

{
"items": [
{
"codRelogioExtChave": "10;1",
"codFuncMsa": "529",
"codNsr": 0,
"codCPF":"",
"numVersLayout": 0,
"codPisMsa": "15423654711",
"codFuso": "",
"datMarcacAces": "2021-10-21 09:30:00.000",
"numHorarMarcacAces": 34200,
"codRep": "",
"codUnidExtChave": "10;1",
"codUsuarExtChave": "10;1;529",
"codCCT":""
},

{
"codRelogioExtChave": "10;1",
"codFuncMsa": "1356",
"codNsr": 0,
"codCPF":"",
"numVersLayout": 0,
"codPisMsa": "15423654711",
"codFuso": "",
"datMarcacAces": "2021-10-23 22:00:00.999",
"numHorarMarcacAces": 79200,
"codRep": "",
"codUnidExtChave": "10;1",
"codUsuarExtChave": "10;1",
"codCCT":""
}

]
}

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:

Expandir

title	Retorno Portaria 1510

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

Expandir

title	Retorno Portaria 671 REP-A

{
"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."
}
]
}

Expandir

title	Retorno Portaria 671 REP-C

{
"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":"",
"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":"",
"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."
}
]
}

Expandir

title	Retorno Refeitório

{
"items": [
{
"codRelogioExtChave": "10;1",
"codFuncMsa": "529",
"codNsr": 0,
"codPisMsa": "17962727770", ou "codCPF": "02709509903",
"datMarcacAces": "2021-10-21 09:30:00.000",
"numHorarMarcacAces": 34200,
"codRep": "",
"codUnidExtChave": "10;1",
"codUsuarExtChave": "10;1;529",
"status": 200,
"errorCode": "",
"codCCT":"",
"message": "Marcação gravada com sucesso"
},
{
"codRelogioExtChave": "10;1",
"codFuncMsa": "1356",
"codNsr": 0,
"codPisMsa": "10699643292", ou "codCPF": "02709509903",
"datMarcacAces": "2021-10-22 22:00:00.999",
"numHorarMarcacAces": 79200,
"codRep": "",
"codUnidExtChave": "10;1",
"codUsuarExtChave": "10;1",
"status": 400,
"errorCode": "00006",
"codCCT":"",
"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, o log detalhado e o log técnico. que são:

- Log Detalhado: são apresentadas informações sobre cada batida que foi lida no momento em que ocorreu a integração, identificando se houve houveram erros, a descrição do erro, o total de batidas lidasrecebidas, o total de batidas com e sem erroerros 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 recebidos para integração da marcação e a hora do evento) da comunicação por meio da API entre o Suricato e TOTVS

Configuração dos Logs

- .

Informações

title	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(A configuração dos Logs é feita pelo programa PE0400 Configurador de Logs Processos MPE, após sua configuração a geração do log é ativada, ao desmarcar as opções que ativam os logs o processo de geração é encerrado.

As configurações disponíveis são:

), 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:

Gerar os logs Detalhado e Técnico em conjunto, ou de forma unitária:
- No log detalhado, opção Gerar Arquivo Log Detalhado na tela, apresenta informações sobre cada batida que foi lida no momento em que ocorreu a integração, se houve erros, o total de batidas lidas, total de batidas com e sem erro.
- No log técnico, opção Gerar Arquivo Log Técnico na tela, apresenta informações técnicas (o json contendo os dados recebidos para integracção) da comunicação por meio da API entre o Suricato e TOTVS Datasul

Existem duas opções para gerar os arquivos de logs:A opção

Por Execução da API,

gera um arquivo a cada vez que

ocorre

a

ocorre a execução da api

r

ecordClockMarkings para

integrar

recordClockMarkings para integrar as marcações do Suricato para o TOTVS Datasul.

O nome

O nome de cada arquivo contém a data e hora de sua criação para identificação.

A opçã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.

O Documento de Referência do PE0400, está disponível com a descrição mais detalhada e completa das funcionalidade.

- Configurador de Logs Processos MPE

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. Obs.: Não é recomendada a geração contínua destes logs, pois, podem causar problemas de espaço em disco.

Detalhamentos das mensagens dos

logs

Logs

Mensagens do

Log

detalahdo

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

para identificar

ao tentar

integrar

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

quando informado caractere diferentes de números

no campo NSR (codNsr), quando informado caracteres diferentes de números
9991	Indica erro

quando o valor for igual a zero

no campo NSR (codNsr)

, quando o valor for zero
9990	Indica erro de duplicidade de marcação,

identificada pelo

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,

identificada pelo

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
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:

informados forem mais de dois
quando o primeiro valor estiver em branco
quando o segundo valor estiver em branco

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 ao tentar integrar uma marcação. O

Indica erro no campo de código do funcionário

,

(codFuncMsa

, está em branco

), quando o valor informado for branco ou vazio
9977	Indica erro ao não encontrar

por

um funcionário, com código da empresa, código do estabelecimento e código do funcionário

com base no que está

informado no campo chave externa do usuário (codUsuarExtChave)

Mensagens do


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

Páginas filhas

Versões comparadas

Versão antiga 99

Nova versão Atual

Chave

INTEGRAÇÃO

Contexto de Negócio (Introdução)

Sistemas Envolvidos

Pré-requisitos instalação/implantação/utilização

Integração

Parâmetros e Chamada do Método:

Exemplos do Json de Request da API:

Situações de Erros Tratados

Exemplo de retorno da API recordClockMarkings:

Checklist de suporte da aplicação

Logs da Integração de Marcações

Contexto

Configuração dos Logs

Configuração dos Logs

Detalhamentos das mensagens dos

Logs

Páginas filhas

Histórico da Página

Versões comparadas

Versão antiga 99

Nova versão Atual

Chave

INTEGRAÇÃO

Contexto de Negócio (Introdução)

Sistemas Envolvidos

Pré-requisitos instalação/implantação/utilização

Integração

Parâmetros e Chamada do Método:

Exemplos do Json de Request da API:

Situações de Erros Tratados

Exemplo de retorno da API recordClockMarkings:

Checklist de suporte da aplicação

Logs da Integração de Marcações

Contexto

Configuração dos Logs

Configuração dos Logs

Detalhamentos das mensagens dos

Logs