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

Integração

O objetivo desta integração é permitir que o Suricato efetue a integração das marcações de ponto e o Datasul efetua 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.

Arquitetura (Tecnologia)
- Esta integração é realizada através da API REST recordClockMarkings, com o método POST.

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

Versões mínima do TOTVS/Datasul: 12.1.27
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.
Parâmetros de conexão devem estar cadastrados corretamente no CD0387: URL, Porta, Usuário e Senha, além de estar marcado para integrar com Middleware.

Processos

O Sistema requisitante enviará as informações via Json para a interface de integração, desta forma será gerado um novo registro na tabela de processos no HCM. Caso tenha êxito na geração do registro, será retornado a mesma estrutura de Json confirmando sua gravação, caso contrário enviará as informações de inconsistências citadas nos próximos tópicos.

Limitações / Restrições Gerais

Com o objetivo de manter a estrutura e a agilidade da estrutura Rest, o Web Service Rest receberá registro individual de cada processo.
A integração não contemplará exclusão de registros no HCM, para isso o usuário deverá acessar o HCM e excluir manualmente o mesmo e seus devidos relacionamentos.

Como realizar a chamada da API REST

Para realizar a integração, é necessário as informações básicas para cadastramento do processo.

Preenchimento do EndPoint da API administrativeJudicialProceedings;
Utilizar a chamada do método Post e do Serviço administrativeJudicialProceedings;
Preenchimento dos parâmetros obrigatórios da API;

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": 1,
"codCPF":"",
"numVersLayout": 0,
"codPisMsa": "15423654711",
"codFuso": "",
"datMarcacAces": "2021-10-21 09:30:00.000",
"numHorarMarcacAces": 34200,
"codRep": "5009940099846",
"codUnidExtChave": "10;1",
"codUsuarExtChave": "10;1;529",
"codCCT":""
},

{
"codRelogioExtChave": "10;1",
"codFuncMsa": "1356",
"codNsr": 2,
"codCPF":"",
"numVersLayout": 0,
"codPisMsa": "15423654711",
"codFuso": "",
"datMarcacAces": "2021-10-23 22:00:00.999",
"numHorarMarcacAces": 79200,
"codRep": "5009940099846",
"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": "",
"codFuncMsa": "529",
"codNsr": 1,
"codPisMsa": "17962727770", ou "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,
"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."
}
]
}

Parâmetros de Entrada:

Parâmetro

Valor de Exemplo

Obrigatório

Tipo

Valor Default

Descriçãoauthorization usuario:senhaSim

header

autenticação é importante para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.contentrequest da apisimbody

Estrutura json com informações de cadastro do processo:

Propriedades Obrigatórias:

Dados do Processo:

tpProc: Tipo de Processo conforme leiaute do eSocial.
nrProc: Número do Processo.
iniValid: Início da Validade do Processo.
indMatProc: Indicativo de Matéria do Processo ou Alvará Judicial.

Dados da Suspensão:

companyCode: Empresa que a suspensão se aplica.
baseCompanyId: Caso não seja informado o código da empresa que a suspensão se aplica, deve ser informada a base do CNPJ da Empresa que a suspensão se aplica.
codSusp: Código indicativo da suspensão.
indSusp: Indicativo de suspensão da exigibilidade conforme leiaute do eSocial.
dtDecisao: Data da decisão.
indDeposito: Indicativo de depósito do Montante Integral.

Parâmetros e Chamada do Método:

Autenticação do tipo básica.

Método POST.

{protocolo}://{host}/api/rh/v1/administrativeJudicialProceedings

Request da API: Exemplo:

Image Removed

Dados utilizados da API

Propriedade API RESTCAMPO HCMDESCRIÇÃOFormato / ExemplocompanyCodecdn_empresaEmpresa que a suspensão se aplica. 123baseCompanyIdcod_base_id_federBase do CNPJ da empresa que a suspensão se aplica. Será considerado apenas quando o código da empresa (companyCode) não for informado. 12345678tpProcidi_tip_proces_justicTipo de processo conforme leiaute do eSocial. 1nrProccod_proces_justicNúmero do processo. 12345678901234567890iniValiddat_inic_validInício da validade do processo. "2019-02"fimValiddat_term_validFim da validade do processo. "9999-12"indAutoriaidi_tip_autoriaAutoria da ação judicial. 2indMatProcidi_mater_procesIndicativo da matéria do processo ou alvará judicial.5observacaodes_obs_spedObservações relacionadas ao processo. Lorem ipsum dapibus molestie semper malesuada aliquam purus suspendisse tristique, etiam per urna arcu ante curabitur quam quis metus tempus, egestas a massa euismod sem fermentum maecenas sodales. vulputate molestie faucibus ac accumsan.ufVaracod_uf_varaUF da Vara. SCcodMuniccdn_munpio_spedCódigo do município, conforme tabela do IBGE. 1234567idVaracod_varaCódigo de Identificação da Vara. 1234infoSuspPode ter nenhuma ou várias suspensões conforme o processo. codSuspnum_seq_utilizCódigo indicativa da suspensão. 1indSuspidi_tip_decis_proces_justicIndicativo de suspensão da exigibilidade. "04"dtDecisaodat_decisData da decisão, sentença ou despacho. "2019-07-21"indDepositolog_depos_montanteIndicativo de depósito do montante integral.

"S" para sim

"N" para não.

Situações de Erros Tratados

O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros. Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.

Tratamento de erros de integração Datasul HCM:

Mensagens de Pré-Validação

Erro

Mensagem

Solução

API RESPONSE

265

Processo (nrProc) deve ser informado(a).

Verificar se a propriedade json nrProc está preenchida no pacote enviado .

Bloco de código

theme	Eclipse
linenumbers	true
collapse	true

{
   			"message": "Processo (nrProc) deve ser informado(a).\n",
    		"code": "265",
    		"type": "error"
}

158

Informe um(a) Tipo Processo (tpProc) válido(a). Valores Válidos: 1 ou 2 ou 3

Verificar se a propriedade json tpProc existe e está com valor válido conforme leiaute do eSocial.

Bloco de código

theme	Eclipse
linenumbers	true
collapse	true

{
   			"message": "Informe um(a) Tipo Processo (tpProc) válido(a). Valores Válidos: 1 ou 2 ou 3.\n",
    		"code": "158",
            "type": "error"
}

56650

Processo cadastrado(a) no HCM deve ser mantido neste produto. Verifique o FP0030.

Se o processo já foi cadastrado pelo HCM (FP0030), a manutenção do mesmo deve ocorrer no HCM e não via integração.

Bloco de código

theme	Eclipse
linenumbers	true
collapse	true

{
   			"message": "Processo cadastrado(a) no HCM deve ser mantido neste produto. Verifique o FP0030.\n",
    		"code": "56650",
            "type": "error"
}

7137

Empresa não relacionada com Nenhum Empregador.

Empresa informada na integração (companyCode) deve ser um empregador ou estar relacionado a algum empregador. Verifique complemento do eSocial no FP0500 Manutenção Parâmetros Empresa RH.

Bloco de código

theme	Eclipse
linenumbers	true
collapse	true

{
   			"message": "Empresa não relacionada com Nenhum Empregador",
    		"code": "7137",
            "type": "error"
}

53817

Dado Registro infoSusp (codSusp: 1) incorreto - indSusp (50).

Este campo (indSusp) deve ter valor conforme leiaute do eSocial.

Bloco de código

theme	Eclipse
linenumbers	true
collapse	true

{
   			"message": "Dado Registro infoSusp (codSusp: 1) incorreto - indSusp (50).",
    		"code": "53817",
            "type": "error"
}

OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma ou não estejam de acordo com o leiaute do eSocial. Vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.

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.

EMS2:

Verificar se os parâmetros de conexão foram cadastrados corretamente no CD0387: URL, Porta, Usuário e Senha.
Verificar se estão cadastrados corretamente os processos no CD2021 dentro do período selecionado no CD2014.
Verificar se o processo (CD2021) está relacionado ao estabelecimento (CD2021A).

Páginas filhas

Versões comparadas

Versão antiga 4

Nova versão 67

Chave

INTEGRAÇÃO

Contexto de Negócio (Introdução)

Sistemas Envolvidos

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

Integração

Integração

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

Limitações / Restrições Gerais

Como realizar a chamada da API REST

Parâmetros e Chamada do Método:

Situações de Erros Tratados

Parâmetros de Entrada:

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 4

Nova versão 67

Chave

INTEGRAÇÃO

Contexto de Negócio (Introdução)

Sistemas Envolvidos

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

Integração

Integração

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

Limitações / Restrições Gerais

Como realizar a chamada da API REST

Parâmetros e Chamada do Método:

Situações de Erros Tratados

Parâmetros de Entrada:

Situações de Erros Tratados

Checklist de suporte da aplicação