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 a empresa e código do relógio informado no programa PE0620 campo. Obrigatório ser informado quando a marcação for de refeitório.
items.codFuncMsa	Código do funcionário	Caracter	Sim	Código Preenchido com a matrícula do funcionário , de acordo com o que está cadastrado no TOTVS Datasulinformado no programa FP1500
items.codNsr	Código NSR	Numérico	Sim
items.codPisMsa	Código do PIS do Funcionário	Caracter	Sim	obrigatório 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	Código do REP conforme cadastro do TOTVS Datasul
items.codUnidExtChave	Código da Unidade	Caracter	Sim	Informa o código da empresa e estabelecimento (exemplo. Ex.: "99;99)"
items.codUsuarExtChave	Código do usuário	Caracter	Sim	Informa o código da empresa, estabelecimento e matrícula (exemplo: 99;99;4)
items.codFuso	Fuso Horário	Caracter	Sim	obrigatório Obrigatório para marcações realizadas em dispositivos que atendem à portaria 671 ou, dispositivos que atendem a portaria 1510 e que geram a informação do CPF no campo PIS.
items.items.codCPF	Código do CPF do Funcionário	Caracter	Sim	obrigatório Obrigatório para marcações realizadas em dispositivos que atendem à portaria 671 ou, dispositivos que atendem a portaria 1510 e que geram a informação do CPF no campo PIS (primeira posição preenchida com 8 ou 9).
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 obrigatório para marcações realizadas em dispositivos que atendem à portaria 671 ou, dispositivos que atendem a portaria 1510 e que geram a informação do CPF no campo PIS. Quando informado valor 1 indica batidas da portaria 1510 ou valor 3 para batidas da portaria 671.
items.inscrEmp	CNPJ ou CPF do empregador	Decimal	Não
items.codCCT	Código Convenção Coletiva	Decimal	Não	Será enviado no parâmetro Enviado o valor vazio (branco), quando a marcação for originada de um REP da portaria antiga (1510 ou 1510 INMETRO). Será enviado Enviado com o valor do acordo coletivo, quando a marcação for originada de um REP A. Será enviado sem zeros a esquerda. O valor será enviado puro, sem completar com zeros a esquerda até os 17 bytes disponíveis. Enviado o valor vazio (branco), quando a marcação for originada de um equipamento de controle de acesso em refeitório. Enviado sem zeros a esquerda.

Exemplos do Json de Exemplos Request da API:

Marcação Portaria 1510Marcação Portaria 671

Expandir

title	Marcações

Exemplo: Marcação

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

]
}

Marcação Portaria 1510

Marcação Portaria 671 REP-A

Marcação Portaria 671 REP-C

Refeitório

{
"items": [
{
"codRelogioExtChave": "",
"codFuncMsa": "529",
"codNsr": 1,
"codCPF":"",
"numVersLayout": 1,
"codPisMsa": "15423654711",
"codFuso": "",
"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":"",
"numVersLayout": 1,
"codPisMsa": "15423654711",
"codFuso": "",
"datMarcacAces": "2021-10-23 22:00:00.999",
"numHorarMarcacAces": 79200,
"codRep": "5009940099846",
"codUnidExtChave": "10;1",
"codUsuarExtChave": "10;1",
"codCCT":""
}

]
}

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

]
}

{
"items": [
{
"codRelogioExtChave": "",
"codFuncMsa": "4",
"codNsr": 1000,
"codCPF": "02709509903",
"codFuso": "-0300",

{

"numVersLayout": 3,
"

codRelogioExtChave

inscrEmpr": "012457856000158",

"

codFuncMsa

datMarcacAces": "

529

2022-09-08 09:30:00.000",
"numHorarMarcacAces": 34200,
"

codNsr

codRep":

1

"858585565656",

"

codPisMsa

codUnidExtChave": "

15423654711

99;99",

"

datMarcacAces

codUsuarExtChave": "

2021-10-21 09:30:00.000

99;99;4",

"

numHorarMarcacAces

codCCT":

34200,

""

},

"codRep": "5009940099846",

{
"

codUnidExtChave

codRelogioExtChave": "

10;1

",

"

codUsuarExtChave

codFuncMsa": "

10;1;529

4",

}

"codNsr": 1002,

{

"codCPF": "02709509903",
"

codRelogioExtChave

datMarcacAces": "2022-09-08 22:00:00.999",
"numHorarMarcacAces": 79200,
"

codFuncMsa

codFuso": "

1356

-0300",

"

codNsr

numVersLayout":

2

3,

"

codPisMsa

inscrEmpr": "

15423654711

012457856000158",

"datMarcacAces": "

2021

2022-

10

09-

23 22

08 09:

00

30:00.

999

000",

"

numHorarMarcacAces

codRep":

79200

"858585565656",

"

codRep

codUnidExtChave": "

5009940099846

99;99",

"

codUnidExtChave

codUsuarExtChave": "

10

99;99;

1

4"

,

"

codUsuarExtChave

codCCT": "

10;1

"

}

]
}

Exemplo: Marcação Portaria 671

{
"items": [
{
"codRelogioExtChave": "10;1",
"codFuncMsa": "

4

529",
"codNsr":

1000

1,
"codCPF":"

02709509903

",
"

codFuso

numVersLayout":

"-0300"

0,
"

numVersLayout

codPisMsa":

3

"15423654711",
"

inscrEmpr

codFuso": "

012457856000158

",
"datMarcacAces": "

2022

2021-

09

10-

08

21 09:30:00.000",
"numHorarMarcacAces": 34200,
"codRep": "

858585565656

5009940099846",
"codUnidExtChave": "

99

10;

99

1",
"codUsuarExtChave": "

99

10;

99

1;

4

529",
"codCCT":"

19269592961497986

"
},

{
"codRelogioExtChave": "10;1",
"codFuncMsa": "

4",
"codNsr": 1002,

1356",
"

codCPF

codNsr":

"02709509903"

2,
"

datMarcacAces

codCPF":"

2022-09-08 22:00:00.999

",
"

numHorarMarcacAces

numVersLayout":

79200

0,
"

codFuso

codPisMsa": "

-0300

15423654711",
"

numVersLayout

codFuso":

3

"",

"inscrEmpr": "012457856000158

"datMarcacAces": "2021-10-23 22:00:00.999",
"

datMarcacAces

numHorarMarcacAces":

"2022-09-08 09:30:00.000"

79200,
"codRep": "

858585565656

5009940099846",
"codUnidExtChave": "

99

10;

99

1",
"codUsuarExtChave": "

99

10;

99;4

1",
"codCCT":"

19269592961497986

"
}

]
}

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:

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

Páginas filhas

Versões comparadas

Versão antiga 51

Nova versão 56

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:

Situações de Erros Tratados

Checklist de suporte da aplicação

Páginas filhas

Histórico da Página

Versões comparadas

Versão antiga 51

Nova versão 56

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:

Situações de Erros Tratados

Checklist de suporte da aplicação