Integração Protheus x Carol - Importação de Batidas

ÍNDICE

01. OBJETIVO

Apresentar ao usuário final, que faça uso da plataforma Carol para marcações de ponto dos colaboradores, como configurar o Protheus para habilitar a integração automática de marcações.

02. FLUXO DO AMBIENTE

03. VISÃO GERAL

A configuração da integração entre a Carol e Protheus se baseia na configuração de um Schedule que será executado em intervalos previamente definidos, acionando as API's da Carol ou a rotina cadastrada em Menu:

• https://domínioCliente.carol.ai/api/v2/oauth2/token  (API de Autenticação e geradora de Token, onde será realizado os demais acessos\requisições)
• https://domínioCliente.carol.ai/api/v2/queries/named/deviceList (API de Requisição de listagem de dispositivos de ponto cadastrados na Carol)
• https://domínioCliente.carol.ai/api/v2/queries/named/clockinrecordsList (Api de requisição de listagem de marcações por dispositivos na Carol)

04. EXEMPLO DE UTILIZAÇÃO

O cliente utiliza a Carol para as marcações de ponto dentro da empresa, esta empresa possui diversos dispositivos espalhados pela organização.

O Protheus será o responsável por acionar a plataforma Carol, buscar as informações contidas em cada dispositivo e armazenar os registros dentro do módulo SIGAPON. Nos próximos tópicos, os passos serão detalhados:

4.1. PARAMETRIZAÇÃO

Para que haja a devida integração entre os dois sistemas, se faz necessário preencher os parâmetros abaixo:

4.2. CADASTRO DO RELÓGIO CAROL

Para cadastro do relógio, basta acessar no SIGAPON/CADASTRO DO PONTO/RELÓGIOS e preencher os dados da aba geral com atenção especial para os campos:

1. Controle (P0_CONTROL) = "P"  //Relógio de Ponto
2. Tipo Arquivo (P0_TIPOARQ) = "R" //Integração com Carol ou TSA
3. Rep (P0_REP) = "" //Se o relógio for da Carol este campo não deve ser preenchido
4. Com a portaria 671 é necessário informar o tipo do REP (1510, REP-A, REP-C e REP-P). Para um relógio do Clock In teremos apenas duas opções, 1510 e REP-A, em ambos os tipos os sistema irá identificar o funcionário pelo PIS ou CPF da marcação por ser um relógio do Clock In, por este motivo qualquer uma das opções são válidas no cadastro do relógio, porém é necessário verificar qual o tipo do REP do Clock In e preencher corretamente o cadastro do relógio.

4.3. SCHEDULE\MENU

A rotina desenvolvida para a realização de todo o fluxo de requisição para a Carol foi nomeada de PONAPI01, esta rotina não estará disponibilizada em Menu ou pré-carregada no Schedule.

O Processo de Cadastramento será o mesmo utilizado por outras rotinas:

4.3.1. PREENCHIMENTO DO SCHEDULE

1. Acessar o módulo SIGACFG - Configurador;
2. Acessar o caminho do menu AMBIENTE/SCHEDULE/SCHEDULE;
3. Clicar na opção Cadastro no calendário de agendamentos, conforme imagem1 da tela no Tópico 06;
4. O preenchimento é simples e intuitivo para o preenchimento correto do schedule (leia o item 5 abaixo, antes de confirmar o cadastro);
5. Clique o ícone cinza ao lado do botão de confirmar, pois lá se encontra as informações de periodicidade de acionamento da rotina cadastrada (Imagem 2 do Tópico 06);
6. Após a confirmação do cadastramento, será necessário habilitar os agents (Imagem 3 do Tópico 06 ), onde você pode cadastrar manualmente ou pressionar o ícone de radar verde no canto superior direito e os agents serão incluídos automaticamente;
7. Com os agents devidamente cadastrados, o usuário deve pressionar o ícone de pasta do lado esquerdo e ligar Task Manager e Queue Manager (São os gerenciadores da fila de acionamento dos agents) (Imagem 4 do Tópico 06 ).

4.3.2. PREENCHIMENTO DO CADASTRO DA ROTINA NO MENU

1. Acessar o módulo SIGACFG - Configurador;
2. Acessar o caminho do menu AMBIENTE/CADASTROS/MENU;
3. Selecione o módulo\Menu que deseja realizar a inclusão da rotina, conforme imagem 1 do Tópico 06;
4. Quando clicar em "OK" será aberta uma tela semelhante a imagem 2 do Tópico 06 e você deverá pressionar o primeiro botão central "Adicionar>>" e o menu inteiro será transferido para o lado direito da tela;
5. Clique na pasta azul que desejar incluir o item da rotina e pressione o botão Novo Item conforme imagem 3 do Tópico 06, desta forma será exibida uma nova tela para inclusão da rotina conforme imagem 4;
6. Preencha o nome que deseja que apareça no menu e digite o nome da rotina citada no início deste documento PONAPI01, conforme imagem 4;
7. Confirme o cadastro e clique no botão central de Gerar;
8. O Sistema exibirá uma mensagem solicitando o nome do xnu que será gerado, sugerimos manter o mesmo nome do xnu padrão ex.

05. PORTARIA 671

Para atender a portaria 671/2021 para a integração de marcações do Clock In será necessário a criação de novos campos nas tabelas MSA_CONTROL_MARCAC, RR1, SP8, SPG, RFE e RFH. Os novos campos irão armazenar o CPF e a convenção coletiva da marcação.

Após a execução do UPPDISTR os seguintes campos serão criados:

SP8

SPG

RFE

RFH

RR1

Para os clientes que utilizam a integração com o Clock e armazenam as marcações na tabela MSA_CONTROL_MARCAC, será necessário realizar a compilação do pacote de fontes, com o fonte atualizado a próxima execução da integração criará automaticamente o novo campo na tabela MSA_CONTROL_MARCAC.

MSA_CONTROL_MARCAC

06. CONFIGURAÇÃO SSL

Para realizar requisições para a Carol, será necessária a configuração do SSL no Appserver. Atualmente a Carol utiliza a versão SSL 1.3 e por este motivo é necessária a configuração do SSL por parte do Protheus. Segue abaixo um exemplo da configuração:

Para mais informações de como realizar a configuração do SSL no AppServer, no final da desta documentação, em anexos, estará disponível o link do passo a passo de como realizar a configuração.

07. TELA DE CADASTRO DE SCHEDULE  

Cadastro de Rotina

Preenchimento da periodicidade dos acionamentos:

Interface de Agents.

Gerenciamento da fila e execução dos agents.

08. TELA DE CADASTRO DE MENU

Tela de listagem de menus

Tela de configuração do menu escolhido

09. CONVERSÃO DE HORAS

O horário da marcação do Clock In é integrada em segundos ou seja, se o funcionário realizou uma marcação às 02:00 teremos salvo na tabela de integração a quantidade total de segundos de 7200. Para achar o horário da marcação em horas e minutos é utilizado a fórmula abaixo dos exemplos:

Exemplos de conversão:

1º Exemplo - Total de segundos da marcação 43239
Total de segundos divido por 3600 para achar a quantidade de horas
43239/ 3600 = 12,01083333333333 → 12 horas
Resto da divisão multiplicado por 60 e o resultado tem o arredondamento aplicado para retirar as casas decimais para encontrar a quantidade de minutos 
0,01083333333333 * 60 = 0,65 (arredondando teremos 1) → 1 minuto

Hora da marcação: 12:01

2º Exemplo - Total de segundos da marcação 65710
Total de segundos divido por 3600 para achar a quantidade de horas
65710/ 3600 = 18,25277778 → 18 horas
Resto da divisão multiplicado por 60 e o resultado tem o arredondamento aplicado para retirar as casas decimais para encontrar a quantidade de minutos 
0,25277778 * 60 = 15,16666666666667 (arredondando teremos 15) → 15 minutos

Hora da marcação: 18:15

10. MENSAGENS DE INTEGRAÇÃO

Para possibilitar o acompanhamento  da integração do Protheus com a Carol, será apresentado algumas mensagens em tela caso o acionamento seja manual pelo menu ou no console.log, quando a rotina for acionada via Schedule.

• Caso o código NSR enviado por parâmetro e o mesmo seja abaixo de zero:
  • Verifique o Código NSR Informado, pois o mesmo somente aceita números positivos!
• Inconsistências nas datas:
  • Verifique as Datas informadas para acesso ao Clock In da Carol.
• Será apresentada a seguinte mensagem e a mensagem retornada da plataforma Carol.
  • Não foi possível acessar a API Clockin da Carol.
• Problemas com o preenchimento dos parâmetros:
  • Verifique o parâmetro MV_APICLO1 pois ele é responsável pelo cadastro da URL de EndPoint para a integração de Clock In da Carol.
  • Verifique o parâmetro MV_APICLO2 pois ele é responsável pelo cadastro do path da API Token para a integração de Clock In da Carol.
  • Verifique o parâmetro MV_APICLO3 pois ele é responsável pelo cadastro do Id Conector para a integração de Clock In da Carol.
  • Verifique o parâmetro MV_APICLO4 pois ele é responsável pelo cadastro do User Name para a integração de Clock In da Carol.
  • Verifique o parâmetro MV_APICLO5 pois ele é responsável pelo cadastro do Password para a integração de Clock In da Carol.
  • Verifique o parâmetro MV_APICLO6 pois ele é responsável pelo cadastro do Domain Name para a integração de Clock In da Carol.
  • Verifique o parâmetro MV_APICLO7 pois ele é responsável pelo cadastro do path da API DeviceList para a integração de Clock In da Carol.
  • Verifique o parâmetro MV_APICLO8 pois ele é responsável pelo cadastro do path da API clockinrecordsList para a integração de Clock In da Carol.
  • Não foi possível acessar a API Clock In da Carol. Verifique os parametros MV_APICLO0, MV_APICLO1, MV_APICLO2, MV_APICLO3, MV_APICLO4, MV_APICLO5, MV_APICLO6,MV_APICLO7, MV_APICLO8 com as informações fornecidas.
  • Não foi possível acessar a API Clock In da Carol. Verifique os parametros MV_APICLO0, MV_APICLO1, MV_APICLO2, MV_APICLO3, MV_APICLO4, MV_APICLO5, MV_APICLO6,MV_APICLO7, MV_APICLO8, MV_APICLO9 com as informações fornecidas.
  • Não foi possível acessar a API Clock In da Carol. Verifique o parametro MV_APICLO8 pois ele é responsável pelo cadastro do path da api clockinrecordsList para a integração de Clockin da Carol.
  • O parâmetro MV_APICLO9 está vazio ou não foi criado e a Carol possui uma organização configurada. Por favor crie e preencha o MV_APICLO9 com o Nome da Organização.

11. TABELAS UTILIZADAS 

• SP0 -  Pré-Leitura\Relógio de Ponto;  
• RFE -  Relógio de Ponto;  
• SP8 - Movimento de Marcações;  
• MSA_CONTROL_MARCAC - Tabela criada na primeira carga de dados com a Carol para armazenar as marcações integradas, caso o dicionário de dados não possua a RR1. Esta tabela também é utilizada no modelo de integração com o TSA e Suricato, a partir deste momento, será processado pelo sistema onde serão gerados os registros na RFE e SP8.
• RR1 - Nova tabela padrão criada para controle total pelo Protheus para o armazenamento das marcações integradas, esta tabela substitui a MSA_CONTROL_MARCAC. Quando identificado que o cliente possui a tabela MSA, é feito uma cópia de dados da MSA para a RR1 e excluída a tabela antiga MSA. A partir deste momento, será processado pelo sistema onde serão gerados os registros na RFE e SP8.

12. ROTINAS ENVOLVIDAS

• GPEA010: Cadastro de Funcionários;
• PONA030: Cadastro de Relógios;
• PONM010: Leitura e Apontamento.

13. ANEXOS

1. DRHGCH-13658 Alterar rotina PONA030 - Relógio (Detalhes para funcionamento na rotina PONA030)
   1. https://tdn.totvs.com/x/kum2Hg
2. DRHGCH-13255 - Integração Ponto X Carol - Batidas - API de acesso ao Token (Detalhes sobre o funcionamento na rotina PONAPI01)
   1. https://tdn.totvs.com/x/34W2Hg
3. DRHGCH-13652 Integração Ponto X Carol - Batidas - API de acesso ao DeviceList
   
   1. https://tdn.totvs.com/x/frC2Hg
4. Seção [SSLConfigure]
   
   1. https://tdn.totvs.com/x/4Ypc