Integração de Publicação da Escala Mensal Completa

A partir da versão 7.3.1.0 do Ponto Soft (solicitação 25475), foi previsto a integração da escala mensal completa, após a publicação no sistema Escala Jornadas.
Desta forma, o sistema Ponto Soft passa a receber, através de um Webhook da API do sistema externo a programação mensal de horários previstos, plantões e folgas de todos os colaboradores que trabalham em regime de escala e estão integrados entre si.

A documentação deste método externo pode ser consultada aqui.

Requisitos

• Ponto Soft: versão 7.3.1.0 ou superior.
• API insoft-escala-jornadas-api: versão 1.4.0 ou superior.

Novas Configurações

A integração da escala mensal completa prevê o recebimento dirário de diverssos eventos, como um horário previsto, um descanso semanal remunerado, folgas programadas e até mesmo ausências planejadas, que atualmente já são integradas como eventos, em casos individuais e isolados.
Esta nova integração da escala mensal completa utiliza em partes a mesma configuração de eventos definida na tela PSW1430 - Integração Eventos com Escala Jornadas, conforme já demonstrado neste post anteior.

A parte adicional de configuração necessária é para a associação de determinados horários no Ponto Soft na aba de Permutas com os horários petencentes a mesma equipe de revezamento.
Isto é necessário para permitir receber a programação de horários previstos destas equipes que trabalham em regime de revezamento ou em turmas, como por exemplo, nos casos de escalas 12 x 36 horas, ou onde o plantão é alternado entre sábados e domingos, sendo necessário criar escalas alternadas no Ponto Soft e ao longo das semanas o colaborador é trocado de horário conforme o dia da escala que ele vai trabalhar.

Já o funcionamento do sistema Escala Jornadas é diferente do sistema Ponto Soft, pois no sistema externo eles cadastram apenas a escala base com os horários previstos e a sequência de dias trabalhados. Somente na hora de associar esta jornada ao colaborador é que se define do dia inicial do ciclo de repetição para este colaborador.

Diante desta situação, é necessário:

• para cada equipe de revezamento deve ser eleito um dos horários do Ponto Soft como o horário base que será associado no sistema Escala Jornadas.
• para o código elegído acima, associar na tela PSW0270 - Cadastro de Horários de Trabalho, na aba "Permuta" todos os códigos de horários do Ponto que esta jornada poderá ser alternada.

Exemplo Configuração de Permuta

Vamos supor que no Ponto Soft temos duas escalas para a mesma equipe de revezamento, o código 7315 para a turma 1 e o código 7316 para a turma 2.

A diferença das duas jorandas é o ciclo da escala: No horário 7315 o descanso semanal e o plantão de 11 horas acontecem no sexto e sétimo dia, respectivamente e na semana seguinte isso é invertido.

Horário 7315

Horário 7316

Além destas duas jornadas acima, também podem existir situações onde o colaborador da equipe de revezamento precisa tirar o seu descanso semanal ou fazer o seu plantão de 11 horas no meio da semana, para cobrir uma folga de outro colaborador, por exemplo.
Para estas situações, são cadastradas "escalas avulsas" e associadas de forma isolda nos dias que isso acontece.

Horário 7099 - Plantão Avulso

Horário 5099 - Folga Avulsa

Para permitir a integração com o Escala Jornadas destas situações, é necessário então eleger uma das duas jornadas que possuem o ciclo de repetição completo para ser associado os demais horários na aba de Permutas.

No nosso exemplo, foi eleito o código de horário "7315" como jornada a ser cadastrada no sistema externo. Desta forma, sempre que um colaborador associado a esta jornada no sistema externo ocorrer o envio da escala mensal publicada ao Ponto Soft, o código da jornada enviado pela API será este código "7315", independente do horário previsto definido em cada dia. Com isto, será possível que a integração "encontre" a jornada prevista que se encaixe no horário inicial e final previsto recebido.

Escopo Técnico

Esta é a terceira entrega do projeto de integração entre Ponto Soft x Escalas Jornadas, com foco na recepção, processamento e aplicação da escala mensal publicada enviada via API, realizando a atualização automática das jornadas previstas e ocorrências no sistema de ponto.

Envio da Escala Mensal Publicada

• Endpoint:
  sendMonthSchedulePublished
• Documentação API:
  https://api-doc.jornadas.escala.app/#tag/Escalas/operation/sendMonthSchedulePublished

Implementação na API "insoft-escala-jornadas-api"

1. Novo método para:
   • Receber os dados da Escala Mensal Publicada.
   • Realizar o parse do payload recebido.
   • Armazenar os dados recebidos em tabela temporária, no formato JSON.
   • Retornar HTTP 200 após o processamento inicial.
2. Após o recebimento:
   • Os registros devem ser lidos da tabela temporária.
   • Inseridos na tabela PONTEIROS_ESCALAS_PUBLICADAS.
   • Os registros devem ser gravados com:
     • SITUACAO = '1'
     • DATA_REGISTRO = SYSDATE
     • USUARIO = Usuário da aplicação
3. Alterar método de callback de Evento para:
   • Receber o novo atributo " working_day_type_external_id".
   • Realizar o parse do payload recebido.
   • Armazenar o novo atributo no campo cod_horario_ponto da tabela ponteiros_eventos_escalas.
   • Endpoint:
     sendEventCreated
   • Documentação API:
     https://api-doc.jornadas.escala.app/#tag/Eventos/operation/sendEventCreated

Implementação no Banco de Dados

Nova Tabela PONTEIROS_ESCALAS_PUBLICADAS

| Coluna                     | Tipo             | Opcional | Observação                                                                 |
|----------------------------|------------------|----------|-----------------------------------------------------------------------------|
| ID                         | NUMBER(19)       | Não      | PK                                                                          |
| DATA_REGISTRO              | DATE             | Não      | Data e hora de inclusão na tabela.                                          |
| ANO_ESCALA                 | NUMBER(4)        | Não      | Ano da escala.                                                              |
| MES_ESCALA                 | NUMBER(2)        | Não      | Mês da escala.                                                              |
| ID_ESCALA                  | NUMBER(10)       | Não      | Identificador da escala gerada.                                             |
| NOME_ESCALA                | VARCHAR2(100)    | Sim      | Nome da escala gerada.                                                      |
| DATA_EVENTO                | DATE             | Não      | Data do evento na escala.                                                   |
| ID_FUNCIONARIO_ESCALA      | NUMBER(20)       | Não      | Identificador do funcionário no sistema de escala.                          |
| COD_FUNCIONARIO            | NUMBER(6)        | Não      | Código do funcionário no ponto.                                             |
| MATRICULA                  | NUMBER(10)       | Não      | Matrícula do funcionário.                                                   |
| ID_EVENTO_ESCALA           | NUMBER(20)       | Não      | Identificador do evento no sistema de escala.                               |
| HORA_INICIAL               | DATE             | Sim      | Hora inicial do evento.                                                     |
| HORA_FINAL                 | DATE             | Sim      | Hora final do evento.                                                       |
| COD_EVENTO_ESCALA          | NUMBER(5)        | Sim      | Código do evento no sistema de escala.                                      |
| INDICA_AUSENCIA            | VARCHAR2(1)      | Sim      | Indica se é uma ausência.                                                   |
| COD_HORARIO_ESCALA         | NUMBER(5)        | Sim      | Código do horário de trabalho no sistema de escala.                         |
| COD_HORARIO_PONTO         | NUMBER(5)        | Sim      | Código do horário de trabalho no sistema de ponto.                         |
| COD_JORNADA_ESCALA         | NUMBER(5)        | Sim      | Código da jornada que gerou o evento.                                       |
| DATA_HORA_CRIACAO_ESCALA   | DATE             | Não      | Data e hora da criação no sistema de escala.                                |
| DATA_HORA_ALTERACAO_ESCALA | DATE             | Sim      | Data e hora da alteração no sistema de escala.                              |
| SITUACAO                   | VARCHAR2(1)      | Não      | Status do registro: 1 - Liberado, 2 - Integrado, 3 - Erro.                  |
| USUARIO                    | VARCHAR2(30)     | Não      | Usuário que inseriu o registro.                                             |
| DATA_PROCESSAMENTO         | DATE             | Sim      | Data e hora de processamento no ponto.                                     |
| OBSERVACAO                 | VARCHAR2(500)    | Sim      | Observação da atualização do registro.                                     |

Implementações PLSQL

1. Nova procedure PACK_INTEGRACAO_ESCALA.INSERE_EVENTO_PONTO

   • Rotina para centralizar a atualização de ocorrências e trocas de horários recebidos como eventos e publicação da escala completa pelo Escala Jornadas.
   • Implementado algoritmo para receber trocas de horários a partir do novo atributo "COD_HORARIO_PONTO", responsável por indicar qual é o código de horário de trabalho base correspondente no Ponto.
   • A partir deste código de horário recebido é percorrido os horários associados entre sí na tabela PERMUTAS_HORARIOS_TRABALHOS.
   • Verificado se os campos HORA_INICIAL e HORA_FINAL, recebidos na integração, coincidem com algum horário previsto entre as jornadas associadas na tabela de permutas.
   • Caso encontre horário previsto iguais aos campos recebidos de hora inicial e final da integração é estabelecido este COD_HORARARIO_TRABALHO como o código a ser associado ao funcionário naquela data de movimentação.
   • Verificado se este código de horário já está associado ao funcionário nesta mesma data de movimentação no Ponto Soft.
   • Caso ainda não estiver definido, é lançado a troca de horário naquela data de marcação.
   • Caso seja recebido uma integração de evento de Ocorrência ou de Troca de Horário via de/para na tabela de parâmetros, continua realizando o mesmo processo já implementado anteriormente.

2. Alteração na PACK_INTEGRACAO_ESCALA.ATUALIZA_EVENTO_PONTO

   • Ajustado rotina para receber o novo atributo COD_HORARIO_PONTO na tabela PONTEIROS_EVENTOS_ESCALAS.
   • Passado a lógica de atualização de ocorrências e trocas de horários no ponto para a procedure interna INSERE_EVENTO_PONTO, para centralizar a regra num único método.

3. Nova procedure PACK_INTEGRACAO_ESCALA.ATUALIZA_ESCALA_PUBLICADA

   • Nova rotina deve buscar os registros na tabela PONTEIROS_ESCALAS_PUBLICADAS pendentes (SITUACAO = '1').
   • Para cada registro recebido acionar a rotina INSERE_EVENTO_PONTO.

4. Novo job de banco PJOB_ATZ_ESCALA_PUBLICADA

   • Job deve chamar a rotina PACK_INTEGRACAO_ESCALA.ATUALIZA_ESCALA_PUBLICADA.
   • Periodicidade: a cada 60 minutos por padrão.

Implementação Web

1. Nova aba "Escala Publicada" na tela PSW1410 - Registros Integrados Escala Jornadas

• Nova aba na PSW1410: "Escala Publicada"
• Tabela Base: PONTEIROS_ESCALAS_PUBLICADAS

2. Alterar aba "Eventos" na tela PSW1410 - Registros Integrados Escala Jornadas

• Novo campo: "Cód. Horário Ponto"
• Campo na base: PONTEIROS_ESCALAS_PUBLICADAS.COD_HORARIO_PONTO

Integração de Eventos com Escala Jornadas

A partir da versão 7.2.9.0 do Ponto Soft (solicitação 25474), foi previsto a integração de eventos do sistema Escala Jornadas para atualização de ocorrências e trocas de horário.
O sistema passa a contar, de forma comercial, integração para o envio de ocorrências e trocas de horários para o Escala e o recebimento de eventos, para atualização como ocorrência ou como troca de horário no Ponto Soft.

Requisitos

• Ponto Soft: versão 7.2.9.0 ou superior.
• API insoft-escala-jornadas-api: versão 1.3.0 ou superior.

Novas Configurações

Eventos de integração entre os sistemas

• Tela PSW1430 - Integração Eventos com Escala Jornadas
• Menu: Frequência > Cadastro > Parâmetros > Eventos de Escala Jornadas
• Tabela: PARAMETROS_EVENTOS_ESCALAS
  Nesta tela devem ser relacionados os códigos de eventos do sistema Escala Jornadas com os tipos de ocorrências ou códigos de horário de trabalho que serão integrados.
  Além disso, é necessário definir o Sentido Integração entre as opções abaixo:
  • Ponto > Escala: lança no Ponto Soft e envia para o Escala.
  • Escala > Ponto: lança no Escala e envia para o Ponto Soft.
  • Ambos: o lançamento pode ser feito em qualquer sistema que será replicado.

Processo

1) Envio de ocorrências e trocas de horários como evento ao Escala

Após implantação da nova versão da API, das configurações acima na tela PSW1430, as movimentações de ocorrências e de troca de horário que estiverem relacionadas a eventos do Escala irão gerar os lançamentos na tabela de ponteiros de eventos PONTEIROS_EVENTOS_ESCALAS, com o valor do campo "Origem" como "Ponto > Escala" e "Situação" com valor "1 - Liberado".

A nossa API é responsável pelo monitoramento dos registros na tabela PONTEIROS_EVENTOS_ESCALAS com SITUACAO igual a "1" e ORIGEM igual a P, para envio aos métodos POST ou DELETE de acordo com o campo OPERACAO.

• Criar um evento

  • URL: https://api-doc.jornadas.escala.app/#tag/Eventos/operation/createEvent
  • Dados enviados
    

• Remover um evento

  • URL: https://api-doc.jornadas.escala.app/#tag/Eventos/operation/deleteEvent

  • Dados enviados
    

  • Atualizar na tabela de ponteiros os dados abaixo após o processamento:

    • SITUACAO com valor "2" em caso de sucesso ou "3" em caro de erro
    • OBSERVACAO com a mensagem de retorno
    • DATA_PROCESSAMENTO com a data e hora atual
    • ID_EVENTO_ESCALA com o Id retornado na responde.

2) Recebimento de eventos do Escala para gerar ocorrência ou troca de horário

A nossa API possui um novo método POST para acionamento pela API do Escala, através de um Webhook.

• URL Webhook da API do Escala: https://api-doc.jornadas.escala.app/#tag/Eventos
• Dados enviados
  
• Este método sempre insere um novo registro na tabela de PONTEIROS_EVENTOS_ESCALAS, atualizando os campos conforme acima.
• Campos de controle
  • ORIGEM atualiza sempre com valor "E"
  • SITUACAO atualiza sempre com valor "1"
  • OPERACAO conforme o atributo action ("I", "A" ou "E")
• Retorna o status 200 para o callback caso sucesso.

Consulta de Registros Integrados

Na tela PSW1410, na nova aba Eventos podem ser visualizado todos os dados gerados, tanto de origem "Ponto > Escala" bem como no sentido "Escala > Ponto", podendo ser solicitado o reenvio de registros com situação "3 - Inconsistente/Erro", pois este status indica um erro ao tentar enviar a informação para o sistema parceiro.

Alterações em Rotinas PL/SQL

1. Envio de eventos do Ponto Soft → Escala Jornadas

Ajustes e novas funcionalidades:

• Inclusão das colunas hora_inicial_ocor e hora_final_ocor na tabela ocorrencias_pontos.
• Atualização da rotina proc_ocorrencias_pontos para determinar o horário inicial e final das ausências.
• Criação de uma nova procedure dentro da pack_ocorrencias_pontos para apuração de horários em ocorrências sem hora_entrada e hora_saida.
• Criação de triggers de integração sobre:
  • ocorrencias_pontos – operações INSERT, UPDATE, DELETE.
  • horarios_trabalhos_funcionario – operações INSERT, UPDATE, DELETE.
• Centralização da inclusão dos registros de integração na procedure pack_integracao_escala.atualiza_ponteiro_evento.

Ajustes na PACK_INTEGRACAO_ESCALA:

• Function controle_trigger - verifica a origem do disparo do processo, para não ficar enviando de volta dados entre os sistemas.
• Function ver_funcionario_escala - valida se o funcionário pode ser enviado para o Escala com base nas configurações de integração por setor ou atributo adicional.
• Function busca_evento_escala – valida integração de tipos de ocorrência ou horário de trabalho (origem “Ponto → Escala”).
• Procedure atualiza_ponteiro_evento – gera e valida registros na tabela ponteiros_eventos_escalas.

2. Recebimento de eventos do Escala Jornadas → Ponto Soft

Novas rotinas e processos:

• Criação de job de banco para monitorar e processar registros na tabela ponteiros_eventos_escala com origem = 'E' e situacao = '1'.

  • Centralização do processamento na nova rotina pack_integracao_escala.atualiza_evento_ponto.

• Criação da procedure atualiza_evento_ponto para:

  • Buscar os eventos pendentes recebidos do Escala.
  • Lançar ocorrência em previsoes_ocorrencias_pontos (eventos tipo “Ocorrência”).
  • Lançar troca de horário em horarios_trabalhos_funcionario (eventos tipo “Troca de Horário”) sempre com data retorno ao horário antigo em D+1.
  • Realizar validações de permissão para cada lançamento, regeração de data em caso de períodos retroativos, recálculo de horas, etc.
  • Marcar o status de integração, data de processamento e observação na tabela ponteiros_eventos_escalas.

Referências

• Informações complementares
  K:\Desenvolvimento\Solicitacoes\25474\DePara_Campos_API.xlsx

A partir da versão 7.1.8.0 do Ponto Soft, foi previsto uma nova opção para definir o envio dos colaboradores ao sistema Escala Jornadas.
O sistema passar a contar, de forma comercial, com a configuração por atributo adicional por colaborador.

Observação: as configurações anteriores não deixam de existir e serem necessárias, foi previsto apenas uma nova opção de definir quais os colaboradores devem ser enviados para o sistema terceiro, além da opção já existente por setor ponto.

Requisitos

• Ponto Soft: versão 7.1.8.0 ou superior.
• API insoft-escala-jornadas-api: versão 1.0.2 ou superior.

Configurações

Parâmetro Customizado ENVIO_COLABORADORES_ESCALA

Criar parâmetro customizado ENVIO_COLABORADORES_ESCALA.
Parâmetro para definir como os colaboradores devem ser integrados com o sistema Escala Jornadas.

• Valores Permitidos no parâmetro ENVIO_COLABORADORES_ESCALA:
  • "SETOR"
    A integração será realizada com base no setor de ponto.
    O indicador "Integração Escala" deve estar ativado no cadastro do setor no módulo PSW0170.
  • "ATRIB_ADICIONAL"
    A integração será realizada com base em um atributo adicional.
    Esse atributo adicional deve ser associado ao cadastro do colaborador no módulo PSW0250 ou PSW6140.
    O código do atributo adicional utilizado para integração deverá ser definido no parâmetro customizado "COD_ATRIBUTO_ENVIO_ESCALA".

Parâmetro Customizado COD_ATRIBUTO_ENVIO_ESCALA

Caso a escolha do cliente seja para integrar os colaboradores através do atributo adicional, criar o parâmetro customizado COD_ATRIBUTO_ENVIO_ESCALA.
Este parâmetro define o código do atributo adicional do colaborador que será utilizado para configurar a integração com o sistema Escala Jornadas.
Este parâmetro funciona em conjunto com o parâmetro customizado "ENVIO_COLABORADORES_ESCALA", quando o valor do parâmetro for definido como "ATRIB_ADICIONAL", a integração com o sistema Escala Jornadas dependerá da associação do atributo adicional especificado neste parâmetro ao colaborador.

Atributo Adicional

Criar atributo adicional, alfanumérico, sem data de vigência, para definir se o colaborador deve ser integrado com o sistema de escala.
Este atributo será necessário apenas se o parâmetro customizado "ENVIO_COLABORADORES_ESCALA" for configurado com o valor "ATRIB_ADICIONAL".

Associar Atributo por Colaborador

A associação do novo atributo adicional para definir se integração com o sistema de escala, pode ser associado através da tela PSW0250 ou PSW6140.
Deve ser preenchido com o valor "S".