Í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, 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.
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.1415, 12.1.2503.910, 12.1.2507.3 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 e gravação das marcações destas marcações, bem como realizar a gravação na tabela marcac_nova_integr.

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

Quando no Ahgora PontoWeb by TOTVS

e poderá receber no método POST os seguintes parâmetros:

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 "99999999999999999".
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 "99999999999999999".
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

id	Exemplos de Json da Requisição da API

Card

label	Marcação REP-A - Portaria 671

{

"items": [

{

PropriedadeDescriçãoTipoObrigatório?ObservaçãoitemsArray das marcaçõesArraySimcodRelogioExtChaveCódigo RelógioCaracterSim

Preenchido com a palavra "PONTO WEB".

codFuncMsaCódigo da Matrícula do funcionárioCaracterSimPreenchido com a matrícula do funcionário conforme codNsrCódigo NSRNuméricoSimcodPisMsaCódigo do PIS do FuncionárioCaracterSimObrigatório para marcações realizadas em dispositivos que atendem à portaria 1510.datMarcacAcesData da marcaçãoCaracterSimnumHorarMarcacAcesHora da marcação em segundosNuméricoSimcodRepCódigo do REPCaracterNãoPreenchido com o número informado no programa PE0620, campo Número REPcodUsuarExtChaveCódigo do usuárioCaracterSimPreenchido com o código da empresa, estabelecimento e matrícula. Ex.: "99;99;4"codFusoFuso Horário CaracterSimObrigatório para marcações realizadas em dispositivos que atendem à portaria 671.codCPFCódigo do CPF do FuncionárioCaracterSimObrigatório para marcações realizadas em dispositivos que atendem à portaria 671.numVersLayoutVersão Layout Arquivo AFDNuméricoSim

Quando preenchido com o valor:

0 - marcações de refeitório

1 - marcações da portaria 1510

3 - marcações da portaria 671

inscrEmpCNPJ ou CPF do empregadorDecimalNãocodCCTCódigo Convenção ColetivaDecimalNã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

codCPF": "

10;1

88888888888",

"codFuncMsa": ["

1356

1"],

"

codNsr

codFuso":

0

"+0300",

"

codCPF

codNsr": "120024",

"

numVersLayout

codRelogioExtChave":

0

"PONTOWEB",

"

codPisMsa

codRep": "

15423654711

80008000800080008",

"

codFuso

codUsuarExtChave": ["10;1;1"],

"datMarcacAces": "

2021

2025-

10

08-

23 22

04T08:00:00.

999

000",

"numHorarMarcacAces":

79200

28800,

"

codRep

numVersLayout": "

",
"codUnidExtChave": "10;1

3",

"

codUsuarExtChave

codCCT": "

10;1

80008000800080008",

"

codCCT

inscrEmp":"11112222333344"

}

]
}

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:

statuserrorCodemessageOBS200Marcação gravada com sucesso.40000001PIS em formato inválido ou inexistente no cadastro.40000002NSR duplicado. Número já foi importado na tabela marcac_nova_integr .40000003NSR não foi informado e é obrigatório.40000006É obrigatório informar o campo codRelogioExtChave.40000006É obrigatório informar o campo codFuncMsa.40000006É obrigatório informar o campo codPisMsa.Somente quando não estiverem informados os campos: codPisMsa e codCPF 40000006É obrigatório informar o campo datMarcacAces.40000006É obrigatório informar o campo numHorarMarcacAces.40000006É obrigatório informar o campo codRep.40000006É obrigatório informar o campo codUnidExtChave.40000006É obrigatório informar o campo codUsuarExtChave.40000006Campo 'codRelogioExtChave' no formato incorreto. Deve ser preenchido como texto e conter o código da empresa e do relógio no ERP.40000006Campo 'codNsr' no formato incorreto. Deve ser preenchido como numérico.40000006Campo 'numHorarMarcacAces' no formato incorreto. Deve ser preenchido como numérico.40000006Campo 'codUnidExtChave' no formato incorreto. Deve ser preenchido como texto e conter o código da empresa e do estabelecimento no ERP.40000006Campo '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.40000006Foi enviado marcações de um relógio que não está cadastrado no ERP40000006

Verifique codCPF informado

Somente quando o campo codCPF estiver informado e seu dígito verificador estiver incorreto.

},
{ "codCPF": "88888888888",
"codFuncMsa": ["1"],
"codFuso": "+0300",
"codNsr": "120025",
"codRelogioExtChave":"PONTOWEB",
"codRep": "80008000800080008",
"codUsuarExtChave": ["10;1;1"],
"datMarcacAces": "2025-08-04T16:00:00.000",
"numHorarMarcacAces": 57600,
"numVersLayout": "3",
"codCCT": "80008000800080008",
"inscrEmp":"11112222333344"
}
]
}

Card

label	Marcação REP-P - Portaria 671

{
"items": [

{
"codCPF": "88888888888",
"codFuncMsa": ["1"],
"codFuso": "+0300",
"codNsr": "120024",
"codRelogioExtChave":"PONTOWEB",
"codRep": "77744455522211177",
"codUsuarExtChave": ["10;1;1"],
"datMarcacAces": "2025-08-04T08:00:00.000",
"numHorarMarcacAces": 28800,
"numVersLayout": "3",
"inscrEmp":"11112222333344"

},
{ "codCPF": "88888888888",
"codFuncMsa": ["1"],
"codFuso": "+0300",
"codNsr": "120025",
"codRelogioExtChave":"PONTOWEB",
"codRep": "77744455522211177",
"codUsuarExtChave": ["10;1;1"],
"datMarcacAces": "2025-08-04T16:00:00.000",
"numHorarMarcacAces": 57600,
"numVersLayout": "3",
"inscrEmp":"11112222333344"
},

Exemplo de retorno da API recordClockMarkings:

Expandir

title	Retorno Portaria 1510

{
"items": [

{

"

codRelogioExtChave

codCPF": "15974125460",

"

codFuncMsa

codFuso": "

529

+0300",

"codNsr":

1

"8501",

"

codPisMsa

codRelogioExtChave":"

17962727770

PONTOWEB",

"

datMarcacAces

codRep": "

2021-10-21 09:30:00.000

12121212121212121",

"

numHorarMarcacAces

codFuncMsa":

34200

["80","125"],

"

codRep

codUsuarExtChave":

"5009940099846"

["10;1;80","10;1;125"],

"

codUnidExtChave

datMarcacAces": "

10;1

2024-07-21T08:00:00.000",

"

codUsuarExtChave

numHorarMarcacAces":

"10;1;529"

28800,

"

status

numVersLayout":

200

"3",

"

errorCode

inscrEmp":"77778888999944"

,

}

"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

]
}

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.
400	00006	Não foi localizado funcionário com o CPF informado.	Somente para marcações realizadas por funcionários com múltiplo vínculo no mesmo CNPJ, quando não localizar nenhum funcionário ativo no dia da marcação para o CPF informado.

Exemplo de retorno da API recordClockMarkings

Deck of Cards

id	Exemplo de Json Retorno da API recordClockMarkings

Card

label	Retorno Marcações REP-A - Portaria 671

{
"items": [

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

codCPF":

"Marcação gravada com sucesso"

"88888888888",

}

"codFuncMsa": ["1"],

{

"codFuso": "+0300",
"

codRelogioExtChave

codNsr": "120024",

"

codFuncMsa

codRelogioExtChave":"

1356

PONTOWEB",

"

codNsr

codRep":

2

"80008000800080008",

"

codCPF

codUsuarExtChave": ["

02709509903

10;1;1"],

"datMarcacAces": "

2021

2025-

10

08-

22 22

04T08:00:00.

999",
"numHorarMarcacAces": 79200

000",

"

codRep

numHorarMarcacAces":

"5009940099846"

28800,

"

codUnidExtChave

numVersLayout": "

10;1

3",

"

codUsuarExtChave

codCCT": "

10;1

80008000800080008",

"status":

400

200,

"errorCode": "

00006

",

"

codCCT

message": "

19269592961497986

Marcação gravada com sucesso",

"

message

inscrEmp":"

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."

11112222333344"

},

]
}

Expandir

title	Retorno Portaria 671 REP-C

{

"

items

codCPF":

[

"88888888888",

{

"codFuncMsa": ["1"],

"

codRelogioExtChave

codFuso": "+0300",

"

codFuncMsa

codNsr": "

529

120025",

"

codNsr

codRelogioExtChave":

1

"PONTOWEB",

"

codCPF

codRep": "

02709509903

80008000800080008",

"

datMarcacAces

codUsuarExtChave": ["

2021-10-21 09:30:00.000"

10;1"],

"

numHorarMarcacAces

datMarcacAces":

34200

"2025-08-04T16:00:00.000",

"

codRep

numHorarMarcacAces":

"5009940099846"

57600,

"

codUnidExtChave

numVersLayout": "

10;1

3",

"

codUsuarExtChave

codCCT": "

10;1;529

80008000800080008",

"status":

200

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

"

message

inscrEmp":"

Marcação gravada com sucesso

11112222333344"

}

},

]
}

Card

label	Retorno Marcações REP-P - Portaria 671

{
"items": [

{

"codCPF": "88888888888",
"

codRelogioExtChave

codFuncMsa": ["1"],

"

codFuncMsa

codFuso": "

1356

+0300",

"codNsr":

2

"120024",

"

codCPF

codRelogioExtChave":"

02709509903

PONTOWEB",

"

datMarcacAces

codRep": "

2021-10-22 22:00:00.999

77744455522211177",

"

numHorarMarcacAces

codUsuarExtChave":

79200

["10;1;1"],

"

codRep

datMarcacAces": "

5009940099846

2025-08-04T08:00:00.000",

"

codUnidExtChave

numHorarMarcacAces":

"10;1"

28800,

"

codUsuarExtChave

numVersLayout": "

10;1

3",

"status":

400

200,

"errorCode": "

00006

",

"

codCCT

message": "Marcação gravada com sucesso",

"

message

inscrEmp":"

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.

11112222333344"

},

]
}

Expandir

title	Retorno Refeitório

{

"

items

codCPF":

[

"88888888888",

{

"codFuncMsa": ["1"],
"

codRelogioExtChave

codFuso": "

10;1

+0300",

"

codFuncMsa

codNsr": "

529

120025",

"

codNsr

codRelogioExtChave":

0

"PONTOWEB",

"

codPisMsa

codRep": "

17962727770

77744455522211177",

ou "codCPF

"codUsuarExtChave": ["

02709509903

10;1"],

"datMarcacAces": "

2021

2025-

10

08-

21 09

04T16:

30

00:00.000",

"numHorarMarcacAces":

34200

57600,

"

codRep

numVersLayout": "3",

"

codUnidExtChave

status":

"10;1"

400,

"

codUsuarExtChave

errorCode": "

10;1;529

00006",

"

status": 200

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

"

errorCode

inscrEmp":"11112222333344"

,

},

"codCCT":"",

{
"

message

codFuncMsa":

"Marcação gravada com sucesso"

[

}

"80",
"125"

{

],
"

codRelogioExtChave

datMarcacAces": "

10;1

2024-07-21T08:00:00.000",

"

codFuncMsa

inscrEmp": "

1356

77778888999944",

"

codNsr

codRelogioExtChave":

0

"PONTOWEB",

"

codPisMsa

errorCode": "

10699643292

",

ou "codCPF

"message": "

02709509903

Marcação gravada com sucesso.",

"

datMarcacAces

codNsr": "

2021-10-22 22:00:00.999

8501",

"numHorarMarcacAces":

79200

"28800",

"

codRep

codFuso": "+0300",
"codUsuarExtChave": [

"codUnidExtChave":

"10;1;80",

"codUsuarExtChave":

"10;1;125"

,

],
"

status

codCPF":

400

"15974125460",
"numVersLayout": "3",
"

errorCode

codRep": "

00006

12121212121212121",

"

codCCT

status":

"",

200

"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.

}
]
}

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

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(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.

Informações

title	Informação

Os arquivos de log serão criados no diretório spool da sessão Progress do Servidor de Aplicação.

Para auxiliar a identificar a localização destes arquivos, a partir das versões 12.1.2503.14, 12.1.2507.8, 12.1.2511.2 e 12.1.2603, no arquivo de clientlog serão impressas duas mensagens informando o local e nome destes arquivos. Para localizar estas mensagens, deve-se procurar no arquivo de clientlog por:

#novaapi apiRecordClockMarkings - Arquivo Log Técnico
#novaapi peapi016 - Arquivo Log Detalhado

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

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(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 Mais 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: 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 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: NSR (codnsr) Código de REP (codRep) PIS (codPisMsa)
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: 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 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
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 brancoda 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: 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 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
9971	Indica que foi criado com sucesso um relógio no programa PE0620, e informa o código deste relógio e o seu número de REP-P.
9970	Indica que não foi localizado funcionário ativo com o CPF informado na data da marcação. Esta validação aplica-se apenas para funcionários que são múltiplos vínculos no mesmo CNPJ.

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 2

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:

Parâmetros e Chamada do Método:

Exemplos do Json de Request da API:

Exemplos do Json de Request da API:

Situações de Erros Tratados

Exemplo de retorno da API recordClockMarkings:

Situações de Erros Tratados

Exemplo de retorno da API recordClockMarkings

Checklist de suporte da aplicação

Checklist de suporte da aplicação

Logs da Integração de Marcações

Contexto

Configuração dos Logs

Logs da Integração de Marcações

Contexto

Configuração dos Logs

Detalhamentos das mensagens dos Logs

Páginas filhas

Histórico da Página

Versões comparadas

Versão antiga 2

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:

Parâmetros e Chamada do Método:

Exemplos do Json de Request da API:

Exemplos do Json de Request da API:

Situações de Erros Tratados

Exemplo de retorno da API recordClockMarkings:

Situações de Erros Tratados

Exemplo de retorno da API recordClockMarkings

Checklist de suporte da aplicação

Checklist de suporte da aplicação

Logs da Integração de Marcações

Contexto

Configuração dos Logs

Logs da Integração de Marcações

Contexto

Configuração dos Logs

Detalhamentos das mensagens dos Logs