Páginas filhas
  • TOTVS HCM x Suricato - Api Rest recordClockMarkings

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

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:


items
PropriedadeDescriçãoTipoObrigatório?Observação
itemsArray das marcaçõesArraySim
temsitems.codRelogioExtChaveCódigo RelógioCaracterNã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.codFuncMsaCódigo do funcionárioCaracterSimPreenchido com a matrícula do funcionário conforme cadastro no programa FP1500
items.codNsrCódigo NSRNuméricoSim
items.codPisMsaCódigo do PIS do FuncionárioCaracterSimObrigatório para marcações realizadas em dispositivos que atendem à portaria 1510.
items.datMarcacAcesData da marcaçãoCaracterSim
items.numHorarMarcacAcesHora da marcação em segundosNuméricoSim
items.codRepCódigo do REPCaracterNãoPreenchido com o número informado no programa PE0620, campo Número REP
items.codUnidExtChaveCódigo da UnidadeCaracterSimPreenchido com o código da empresa e estabelecimento. Ex.: "99;99"
items.codUsuarExtChaveCódigo do usuárioCaracterSim

Request da API: Exemplo:

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

                    {
                         "codRelogioExtChave": "",
                         "codFuncMsa": "1356",
Preenchido com o código da empresa, estabelecimento e  matrícula. Ex.: "99;99;4"
items.codFusoFuso Horário CaracterSimObrigatório para marcações realizadas em dispositivos que atendem à portaria 671.
items.codCPFCódigo do CPF do FuncionárioCaracterSimObrigatório para marcações realizadas em dispositivos que atendem à portaria 671.
items.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

items.inscrEmpCNPJ ou CPF do empregadorDecimalNão
items.codCCTCó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
titleMarcações Portaria 1510

{
    "items": [
                   

     "codNsr": 2,

{
                         "

codPisMsa

codRelogioExtChave": "

15423654711

",
                         "

datMarcacAces

codFuncMsa": "

2021-10-23 22:00:00.999

529",
                         "

numHorarMarcacAces

codNsr":

79200

1,
                         "

codRep"

codCPF:"

5009940099846

",
                         "

codUnidExtChave

codPisMsa": "

10;1

15423654711",
                         "

codUsuarExtChave

datMarcacAces": "

10;1"

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
titleMarcaçã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
titleMarcaçã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
titleRefeitó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:

statuserrorCodemessageOBS
200
Marcaçã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 ERP
40000006

Verifique codCPF informado

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


Exemplo de retorno da API recordClockMarkings:



Expandir
titleRetorno 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
titleRetorno 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
titleRetorno 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": "

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:

statuserrorCodemessage200Marcaçã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.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.40000006

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.

40000006Foi enviado marcações de um relógio que não está cadastrado no ERPExemplo de retorno da API recordClockMarkings:

"
                   }
                 ]
}

Expandir
titleRetorno Refeitório

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

1

0,
                       

   "codPisMsa

"codPisMsa": "17962727770", ou "codCPF": "

17962727770

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": "10;1",
                       "codFuncMsa": "1356",
                       "codNsr":

2

0,
                       "codPisMsa": "10699643292", ou "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."
                   }
                 ]
}



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.