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 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 | Código Preenchido com a matrícula do funcionário , de acordo com o que está cadastrado no TOTVS Datasulconforme 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ãoCódigo do REP conforme cadastro do TOTVS Datasul | Preenchido com o número informado no programa PE0620, campo Número REP |
| items.codUnidExtChave | Código da Unidade | Caracter | Sim | Informa Preenchido com o código da empresa e estabelecimento (exemplo. Ex.: "99;99)" |
| items.codUsuarExtChave | Código do usuário | Caracter | Sim | Informa Preenchido com o código da empresa, estabelecimento e matrícula (exemplo. Ex.: "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.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 | Enviado Preenchido com o valor vazio (branco), quando a marcação for originada de um REP da portaria antiga (1510 ou 1510 INMETRO). Enviado com Preenchido com o valor do acordo coletivo, quando a marcação for originada de um REP A. Enviado Preenchido com o valor vazio (branco), quando a marcação for originada de um equipamento de controle de acesso em refeitório. Será enviado sem Preenchido sem zeros a esquerda. |
Exemplos do Json de Request da API:
| Expandir | ||
|---|---|---|
| ||
|
| Expandir |
|---|
|
{ |
"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, |
" |
datMarcacAces": |
"2022-09-08 09:30:00.000", |
"codRep": " |
858585565656", |
|
"codUnidExtChave": " |
99; |
99", |
"codUsuarExtChave": " |
99;99; |
4" |
|
"codCCT": "19269592961497986" |
} |
|
] |
| Expandir | ||
|---|---|---|
| ||
|
|
|
| Expandir | ||
|---|---|---|
| ||
{ |
529", |
0, |
", |
numVersLayout": |
0, |
codPisMsa": |
"15423654711", |
codFuso": " |
", |
"datMarcacAces": " |
2021- |
10- |
21 09:30:00.000", |
", |
10; |
1", |
10; |
1; |
529", { |
1356", |
0, |
", |
numVersLayout": 0, |
codPisMsa": |
"15423654711", |
", |
|
"datMarcacAces": " |
2021-10-23 22:00:00.999", |
numHorarMarcacAces": |
79200, |
", |
10; |
1", |
10; |
1", |
|
} |
|
|
"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:
] |
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 | ||
|---|---|---|
| ||
{ |
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. |
Verifique codCPF informado
" |
| Expandir | ||
|---|---|---|
| ||
{ |
0, |
", |
0, |
", |
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.
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas