Histórico da Página
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 Folha de Pagamento visa efetuar os cálculos da folha de pagamento para os funcionários, mantendo o controle sobre os valores referentes aos eventos relativos a estes funcionários.
- EMS (módulo Recebimento): O módulo Recebimento visa agilizar e assegurar o recebimento dos materiais da empresa, possibilitando todos os controles necessários dos materiais.
Integração
O objetivo desta integração é permitir que a área do RH, recebam os processos administrativos e judiciais de outros sistemas especializados na área, reduzindo assim o trabalho de inclusão manual de todas as informações dentro do sistema;
- Arquitetura (Tecnologia)
- Esta integração é feita por intermédio de comunicação direta com os Web Services REST (Representation State Transfer) utilizando o formato JSON (JavaScript Object Notation) de serialização de dados.
Escopo
Por intermédio desta integração será disponibilizada a seguinte funcionalidade:
- Ao ser cadastrado ou alterado o processo no Recebimento (CD2021), é possível enviar o mesmo para o RH por meio do programa CD2014, centralizando as informações que serão disponibilizadas para o eSocial.
- Este processo e suas informações de suspensão serão cadastradas no FP0030.
- A partir do momento que estiver cadastrado no FP0030, será gerada ou atualizada mensagem S-1070 correspondente.
Abaixo demonstramos um desenho como esta integração se dará:
Fora do escopo
- Eliminação de processos via integração.
- Alteração de processos previamente cadastrados no HCM. Processos cadastrados no HCM, devem ser mantidos no HCM.
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 | ||
---|---|---|
| ||
|
Expandir | ||
---|---|---|
| ||
{ }, ] |
Expandir | ||
---|---|---|
| ||
|
Expandir | ||
---|---|---|
| ||
{ { ] |
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 | ||
---|---|---|
| ||
{ |
Expandir | ||
---|---|---|
| ||
{ |
Expandir | ||
---|---|---|
| ||
{ |
Expandir | ||
---|---|---|
| ||
{ |
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 de Entrada:
Parâmetro
Valor de Exemplo
Obrigatório
Valor Default
header
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:
Dados utilizados da API
"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
265
Processo (nrProc) deve ser informado(a).
Verificar se a propriedade json nrProc está preenchida no pacote enviado .
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"message": "Processo (nrProc) deve ser informado(a).\n",
"code": "265",
"type": "error"
} |
Informe um(a) Tipo Processo (tpProc) válido(a). Valores Válidos: 1 ou 2 ou 3
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"message": "Informe um(a) Tipo Processo (tpProc) válido(a). Valores Válidos: 1 ou 2 ou 3.\n",
"code": "158",
"type": "error"
} |
Processo cadastrado(a) no HCM deve ser mantido neste produto. Verifique o FP0030.
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"message": "Processo cadastrado(a) no HCM deve ser mantido neste produto. Verifique o FP0030.\n",
"code": "56650",
"type": "error"
} |
Empresa não relacionada com Nenhum Empregador.
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"message": "Empresa não relacionada com Nenhum Empregador",
"code": "7137",
"type": "error"
} |
Dado Registro infoSusp (codSusp: 1) incorreto - indSusp (50).
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"message": "Dado Registro infoSusp (codSusp: 1) incorreto - indSusp (50).",
"code": "53817",
"type": "error"
} |
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).