Histórico da Página

CONTEÚDO

Visão Geral
Menu
Integração
Atualização/Dicionário
Informações Técnicas APIs
Documentos Relacionados

Totvs custom tabs box

tabs	1.Visão Geral,2.Menu,3.Integração,4.Atualização/Dicionário,5.Informações Técnicas - APIs,6.Documentos Relacionados
ids	visao,menu,naveg,dicionario,tech,doc

Totvs custom tabs box items

default	yes
referencia	visao

Desenvolvimento da interface no POUI e das APIs para integrar as informações dos funcionários e afastamentos ao sistema Ahgora.

Aviso

title	Importante

Requisito para a rotina funcionar:

Ativação do servidor REST na porta multiprotocolo, pelo uso da chave app_environment.
A integração depende da aplicação da atualização liberada no pacote de expedição do módulo RH a partir de 2004/0910/2024 e da execução do UPDDISTR com o dicionário diferencial para os releases iguais ou superiores a versão 12.1.033;
Configuração dos parâmetros MV_AHGORA1 e MV_AHGORA2, com o usuário e senha do integrador, esses dados serão disponibilizados pela Ahgora;
Habilitar o parâmetro MV_RHAHGOR, para gerar inclusões e alterações geradas no Protheus na tabela de integração.

Cadastros Básicos para integração

Antes da integração, é necessário que existam cadastros básicos no sistema da Ahgora:

Centro de Custo - Tabela CTT;
Sindicato - Tabela RCE;
Turno de trabalho - Tabela SR6;
Tipos de afastamentos - Tabela RCM;
Verbas - Tabela SRV; - Obs: As verbas serão usadas nos resultados enviados pela Ahgora para o protheus - Ahgora: API - Resultados

Os códigos deverão ser enviados concatenados com empresa/filial(Quando for exclusiva) e código do registro.

Nota

title	Observação

Os cadastros básicos serão realizados pela equipe de implantação. Quem estiver responsável pela implantação deverá extrair os dados do Protheus e concatenar os códigos correspondentes de cada empresa/filial antes de importá-los no sistema Ahgora.

Para essa extração no protheus, pode ser usada a consulta genérica.

Documentação: RH - Linha Protheus - GPE - Consulta de informações em arquivos por Consulta Genérica

Exemplo de extração de dados no protheus:

Meu cadastro de sindicato é compartilhado entre filiais, ou seja, o campo filial está vazio

Tabela RCE de sindicatos com o campo filial vazio:

O código da empresa que vou utilizar é 01:

Recomendamos gerar a tabela pela rotina 'Consulta Génerica'

Caminho no menu: Consultas > Cadastros > Genéricos;

Filtramos a tabela RCE de sindicatos e clicamos duas vezes em cima do nome da tabela:

Ao abrir a tabela, é possível ver que a filial está vazia, logo, é uma tabela compartilhada entre filiais.

Você pode escolher quais campos quer exportar, após isso, pode gerar o arquivo .CSV

O arquivo deverá ser editado para concatenação da empresa + código do sindicato conforme esperado pela Ahgora.

Para o código desse exemplo deverá ficar 0100, 0101, 0102. Onde 01 é o código da empresa seguido pelo código do sindicato.

Exemplo de uma tabela exclusiva por filial. SR6 - Turno de trabalho

Veja que ao abrir a consulta genérica dessa tabela, é mostrado o campo filial, logo, o código nesse caso será Empresa + Filial + Código do turno = 0101001

Totvs custom tabs box items

default	no
referencia	menu

Primeiro, devemos adicionar a nova tela ao menu.

Como sugestão, posicionar dentro do menu Miscelânea no módulo SIGAGPE → Cadastrar o grupo 'Integração Ahgora' e o item 'Integração'

Grupo

Novo Item 'Integração' com a rotina GPEM929 dentro do grupo 'Integração Ahgora'

Clicar em Gerar, preencher com SIGAGPE e clicar em Gerar

Atualizar Status só irá consultar registros com status 'AR' - Aguardando retorno;

Botão Integrar funcionários só ficará habilitado quando houver registro selecionado;

Registros com status 'AR' - Aguardando retorno e 'IN' - Integrados, não serão integrados novamente, para integrar novamente um registro já integrado, ele precisará sofrer alguma alteração no cadastro;

Opção de consultar lote só estará disponível para registros com status diferente de 'NI' - Não integrados;

Após integração, a consulta do retorno com o sistema da Ahgora fica disponível por 1 hora, ou seja, é de extrema importância que após a integração, seja feita a consulta do status para obter o retorno;

Totvs custom tabs box items

default	no
referencia	naveg

Integração e Opções em tela

Aviso

title	Importante

A integração depende das configurações de parâmetros de usuário e senha de integração com Ahgora, bem como atualização da expedição contínua e aplicação do UPDDISTR com atualização do dicionários de dados, essa parte da atualização poderá ser verificada na seção 'Atualização/Dicionário';
Toda integração será gravada na tabela RUM, alterações nos registros dos funcionários e afastamentos, também serão gravados na tabela RUM - Integração Ahgora;
O campo elegibilidade do ponto é obrigatório para o funcionário, veja a seção 'Elegibilidade do Ponto' antes de iniciar a integração.

Ao acessar o novo menu criado, abre-se uma nova tela.

Nessa nova tela, será exibido o menu para integração dos funcionários, afastamentos e exclusões dos afastamento com a Ahgora

Caso exista alguma divergência, será aberto a tela abaixo mostrando o que falta atualizar ou configurar, a tela de integração só será aberta quando não existir pendências de atualizações e configurações.

No exemplo, a porta Multiprotocolo não está habilitada, portanto, a tela de integração não será aberta.

Image Added

Deck of Cards

id	IntegracaoAhgora

Card

id	ponto
label	Elegibilidade do Ponto

Para integração com Ahgora, a elegibilidade do ponto é obrigatório, onde será enviado na integração do funcionário, se o ponto dele é obrigatório ou livre.

Essa configuração deve ser feita antes da integração dos funcionários.

Cadastro do Funcionário - Rotina GPEA010

Para alteração da elegibilidade do ponto do funcionário, onde será informado se ele possuí o ponto obrigatório ou ponto livre, o parâmetro que será usado é o MV_RHAHGOR, com o parâmetro habilitado, ao alterar o cadastro do trabalhador, clicar no menu 'Outras ações' > 'Integração Ahgora', será aberta a tela abaixo.

A tela também será aberta na inclusão do funcionário, ao confirmar o cadastro.

Image Added

Ao salvar, será criado um registro no histórico do trabalhador na tabela SR9, esse registro será usado posteriormente na integração do funcionário com o sistema da Ahgora.

Image Added

Carga Inicial

Também foi desenvolvida uma rotina para efetuar a carga inicial referente a elegibilidade do colaborar para o ponto. No cadastro de funcionários, em "Outras Ações", deve ser utilizada a opção "Integração Ponto - Ahgora":
Image Added

Será aberto um wizard onde poderá ser definidos alguns filtros:

Image Added

E deve ser informado se existe ou não controle de ponto, a data de elegibilidade para o controle, e as filiais que serão processadas:

Image Added

Aviso

title	Importante

A data informada não poderá ser maior que a data atual, e será limitada a data de admissão. Como alternativa poderá ser marcado o checkbox "Usa data de admissão" para que defina o controle desde a admissão de cada funcionário.

Essa rotina deve ser usada para carga inicial, e também para mudanças na elegibilidade em lote. A nova opção será exibida apenas quando a integração com AHGORA estiver ativa.

Card

id	IntegAhgoraLista
label	Integração Funcionários

Inicialmente a tela abre vazia esperando que sejam informados os filtros.

Na tela inicial o filtro é genérico com filial, admissão de/até e qual status da integração deseja filtrar.

Para mais filtros, é necessário acessar a opção de 'Filtros Avançados'

Como sugestão, a 'Data Admissão De' vem preenchida com um mês anterior que a data atual e a 'Data Admissão Até' com a data atual.

Filtros de 'Filial' e 'Data Admissão De' são obrigatórios.

Image Added

Filtro 'Filial' aceita multivalores

Image Added

Na opção de 'Filtros Avançados', é possível realizar mais alguns filtros específicos além dos filtros já apresentados na primeira tela.

Image Added

Selecionando os filtros na tela de filtros avançados ou na tela inicial, e ao clicar no botão 'Aplicar Filtros', o sistema buscará as informações dos funcionários.

Apresentação das Informações

Ao aplicarmos os filtros será apresentada a seguinte tela:

Lista de Funcionários

Ao obter a lista de funcionários, temos as colunas:

Status → Correspondente ao status do registro.

- Legenda verde, Tag 'NI' - Integrados

- Legenda azul, Tag 'IN' - Não integrados

- Legenda vermelha, Tag 'CI' - Com Inconsistências

- Legenda laranja, Tag 'AR' - Aguardando Retorno

Image Added

Matrícula Ahgora → Matrícula composta por Empresa + Filial + Matrícula do funcionário no GPE, campo RA_MAT;
Nome → Nome do funcionário, campo RA_NOME;
Dt. Admissão → Campo RA_ADMISSA;
Dt. Demissão → Campo RA_DEMISSA;
Turno → Turno do funcionário, campo RA_TNOTRAB;
Função → Função do funcionário, campo RA_CODFUNC;
Movimento → Inclusão/Alteração;
Dt. Movimento → Data da movimentação;

Serão listados 100 registros por página, ao final da página será mostrado o botão para carregar mais resultados.

Image Added

Selecionando um registro para integração.

Image Added

Ao integrar o registro, se ocorrer tudo certo, o registro será alterado para 'Aguardando Retorno'.

Image Added

Com o registro com status com legenda laranja, 'Aguardando Retorno', será necessário atualizar o status para que seja feita a consulta com o sistema Ahgora, para que possamos saber se o registro foi aceito ou não.

Image Added

Ao final da atualização do status, o registro será alterado, nesse caso alterou para 'IN' - Integrado, ou seja, o registro foi integrado com sucesso.

Image Added

Registro com erro fica com a legenda em vermelho, e você pode consultar o erro, na opção status que está localizada ao clicar nos 3 pontinhoa na parte direita da tabela.

Image Added

Status

Nesse caso, o retorno do erro para o registro foi o E-mail já cadastrado, erro esse enviado pela Ahgora, ou seja, ela não aceitou o registro, pois o e-mail já está cadastrado em outro funcionário.

Image Added

Consulta lote

A segunda opção é a consulta do lote de envio para o ahgora.

Ao abrir a tela do lote, é possível salvar o arquivo .json.

Image Added

Registros que serão enviados na integração

Propriedades	Descrição	Protheus	Observações
matricula	Matrícula Ahgora	Concatenada com Empresa + Filial + RA_MAT
nome	Nome do funcionário	RA_NOME
pis	Pis do funcionário	RA_PIS
matricula_esocial	Matrícula eSocial	RA_CODUNIC
dataAdmissao	Data de admissão	RA_ADMISSA
dataDemissao	Data de demissão	RA_DEMISSA
escala_padrao	Turno do funcionário	RA_TNOTRAB
lastChangeDefaultSchedule	Data da troca do turno	RUM_DATTUR
ctps	Carteira de trabalho	RA_NUMCP
cargo	Função do funcionário	RA_CODFUNC + Descrição da função
departamento	Categoria do funcionário (Multi Valores separados por vírgula)	RA_DEPTO + Descrição do departamento
sexo	Sexo do funcionário	RA_SEXO
email	E-mail do funcionário	RA_EMAIL
cpf	CPF do funcionário	RA_CIC
rg	RG do funcionário	RA_RG
cnpj	CNPJ da filial do funcionário	M0_CGC
dataCnpj	Data da transferência do funcionário	RUM_DATTRA
centroCusto	Centro de custo do funcionário	RA_CC
regimeTrabalho	Categoria do funcionário	RA_CATFUNC
dataNascimento	Data de nascimento do funcionário	RA_NASC
dataCargo	Data alteração da função	RUM_DATFUN
carga_horaria	Carga horária mensal	RA_HRSMES
bate_ponto	Elegibilidade do ponto	Busca no histórico SR9	DT Ahgora: Inclusão na SR9 sobre o ponto do funcionário
data_troca_elegibilidade_ponto	Troca da Elegibilidade do ponto	Busca no histórico SR9	DT Ahgora: Inclusão na SR9 sobre o ponto do funcionário
matricula_chefia	Matrícula chefia	Busca o gestor do departamento do funcionário
nome_chefia	Nome chefia	RA_NOME
email_chefia	E-mail da chefia	RA_EMAIL
codSindicato	Código do sindicato	RA_SINDICA
dataCodSindicato	Data da troca do funcionário de sindicato	Busca no histórico SR9
telefone	Telefone do funcionário	RA_TELEFON
sem_pis	Envio se o funcionário possuí PIS ou não	Validação interna
custo_da_hora	Custo da hora do funcionário	RA_SALARIO / RA_HRSMES. Para os Horistas, apenas o RA_SALARIO
salario	Salário contratual	RA_SALARIO
codInterno	Código Interno do funcionário	Empresa + filial + matricula separados por pipe
matricula_anterior	Matrícula anterior na transferência	Concatenada com Empresa + Filial + RA_MAT anterior

Aviso

title	Importante

Atualizar Status só irá consultar registros com status 'AR' - Aguardando retorno;
Botão Integrar funcionários só ficará habilitado quando houver registro selecionado;
Registros com status 'AR' - Aguardando retorno e 'IN' - Integrados, não serão integrados novamente, para integrar novamente um registro já integrado, ele precisará sofrer alguma alteração no cadastro;
Opção de consultar lote só estará disponível para registros com status diferente de 'NI' - Não integrados;
Após integração, a consulta do retorno com o sistema da Ahgora fica disponível por 1 hora, ou seja, é de extrema importância que após a integração, seja feita a consulta do status para obter o retorno;

Alterações no Protheus

Rotinas que irão gravar registros para integração do funcionário na tabela RUM(Lote integração Ahgora):

GPEA010/GPEA265 - Cadastro do funcionário;
GPEA180 - Transferência;
GPEM040 - Desligamento;
PONA160 - troca de turno;

Ao incluir um funcionário ou alterar um campo pertinente para Ahgora, será gerado um registro na tabela de integração.

O registro gerado será do tipo 'A', alteração, porém caso não exista, será criado como inclusão "I".

Para transferência, caso exista o registro na tabela de integração, e esse registro ainda não estiver integrado, a transferência será abortada.

Aviso

title	Importante

Essas atualizações na tabela de integração só serão executadas caso o parâmetro MV_RHAHGOR estiver habilitado com conteúdo .T.

Card

id	IntegAhgoraAfast
label	Integração Afastamentos

Inicialmente a tela abre vazia esperando que sejam informados os filtros.

Na tela inicial o filtro é genérico com filial, afastamento de/até e qual status da integração deseja filtrar.

Para mais filtros, é necessário acessar a opção de 'Filtros Avançados'

Como sugestão, a 'Data Afastamento De' vem preenchida com um mês anterior que a data atual e a 'Data Afastamento Até' com a data atual.

Filtros de 'Filial' e 'Data Afastamento De' são obrigatórios.

Apresentação das Informações

Ao aplicarmos os filtros será apresentada a seguinte tela:

Lista de Afastamentos

Ao obter a lista de afastamentos, temos as colunas:

Status → Correspondente ao status do registro.

- Legenda verde, Tag 'NI' - Integrados

- Legenda azul, Tag 'IN' - Não integrados

- Legenda vermelha, Tag 'CI' - Com Inconsistências

- Legenda laranja, Tag 'AR' - Aguardando Retorno

Image Added

Matrícula Ahgora → Matrícula composta por Empresa + Filial + Matrícula do funcionário no GPE, campo RA_MAT;
Nome → Nome do funcionário, campo RA_NOME;
Tipo do afastamento → Tipo e descrição do afastamento, campos, R8_TIPOAFA + RCE_DESCRI;
Dt. Início → Inicio do afastamento, campo R8_DATAINI;
Dt. Fim→ Fim do afastamento, campo R8_DATAFIM;
Movimento → Inclusão/Alteração;
Dt. Movimento → Data da movimentação;

Image Added

O processo de integração e retorno das informações funciona da mesma maneira demostrada na seção 'Integração Funcionários'

Registros que serão enviados na integração

Propriedades	Descrição	Protheus	Observações
matricula	Matrícula Ahgora	Concatenada com Empresa + Filial + RA_MAT
motivo	Tipo do afastamento	R8_TIPOAFA
inicio	Início do afastamento	R8_DATAINI
fim	Fim do afastamento	R8_DATAFIM
cod_interno	Código interno	Empresa + Filial + RA_MAT + R8_SEQ separados por ponto.
operation	Operação	INS	Validação interna

Aviso

title	Importante

Deck of Cards

id	IntegracaoAhgora

Card

id	IntegAhgoraLista
label	Integração Funcionários

Inicialmente a tela abre vazia esperando que sejam informados os filtros.

Na tela inicial o filtro é genérico com filial, admissão de/até e qual status da integração deseja filtrar.

Para mais filtros, é necessário acessar a opção de 'Filtros Avançados'

Como sugestão, a 'Data Admissão De' vem preenchida com um mês anterior que a data atual e a 'Data Admissão Até' com a data atual.

Filtros de 'Filial' e 'Data Admissão De' são obrigatórios.

Image Removed

Filtro 'Filial' aceita multivalores

Image Removed

Na opção de 'Filtros Avançados', é possível realizar mais alguns filtros específicos além dos filtros já apresentados na primeira tela.

Image Removed

Selecionando os filtros na tela de filtros avançados ou na tela inicial, e ao clicar no botão 'Aplicar Filtros', o sistema buscará as informações dos funcionários.

Apresentação das Informações

Ao aplicarmos os filtros será apresentada a seguinte tela:

Lista de Funcionários

Ao obter a lista de funcionários, temos as colunas:

Status → Correspondente ao status do registro.

- Legenda verde, Tag 'NI' - Integrados

- Legenda azul, Tag 'IN' - Não integrados

- Legenda vermelha, Tag 'CI' - Com Inconsistências

- Legenda laranja, Tag 'AR' - Aguardando Retorno

Image Removed

Matrícula Ahgora → Matrícula composta por Empresa + Filial + Matrícula do funcionário no GPE, campo RA_MAT;
Nome → Nome do funcionário, campo RA_NOME;
Dt. Admissão → Campo RA_ADMISSA;
Dt. Demissão → Campo RA_DEMISSA;
Turno → Turno do funcionário, campo RA_TNOTRAB;
Função → Função do funcionário, campo RA_CODFUNC;
Movimento → Inclusão/Alteração;
Dt. Movimento → Data da movimentação;

Serão listados 100 registros por página, ao final da página será mostrado o botão para carregar mais resultados.

Image Removed

Selecionando um registro para integração.

Image Removed

Ao integrar o registro, se ocorrer tudo certo, o registro será alterado para 'Aguardando Retorno'.

Image Removed

Com o registro com status com legenda laranja, 'Aguardando Retorno', será necessário atualizar o status para que seja feita a consulta com o sistema Ahgora, para que possamos saber se o registro foi aceito ou não.

Image Removed

Ao final da atualização do status, o registro será alterado, nesse caso alterou para 'IN' - Integrado, ou seja, o registro foi integrado com sucesso.

Image Removed

Registro com erro fica com a legenda em vermelho, e você pode consultar o erro, na opção status que está localizada ao clicar nos 3 pontinhoa na parte direita da tabela.

Image Removed

Status

Nesse caso, o retorno do erro para o registro foi o E-mail já cadastrado, erro esse enviado pela Ahgora, ou seja, ela não aceitou o registro, pois o e-mail já está cadastrado em outro funcionário.

Image Removed

Consulta lote

A segunda opção é a consulta do lote de envio para o ahgora.

Ao abrir a tela do lote, é possível salvar o arquivo .json.

Image Removed

Registros que serão enviados na integração

Propriedades

Descrição

Protheus

Observações

matricula

Matrícula Ahgora

Concatenada com Empresa + Filial + RA_MAT

nome

Nome do funcionário

RA_NOME

pis

Pis do funcionário

RA_PIS

matricula_esocial

Matrícula eSocial

RA_CODUNIC

dataAdmissao

Data de admissão

RA_ADMISSA

dataDemissao

Data de demissão

RA_DEMISSA

escala_padrao

Turno do funcionário

RA_TNOTRAB

lastChangeDefaultSchedule

Data da troca do turno

RUM_DATTUR

ctps

Carteira de trabalho

RA_NUMCP

cargo

Função do funcionário

RA_CODFUNC + Descrição da função

departamento

Categoria do funcionário (Multi Valores separados por vírgula)

RA_DEPTO + Descrição do departamento

sexo

Sexo do funcionário

RA_SEXO

email

E-mail do funcionário

RA_EMAIL

cpf

CPF do funcionário

RA_CIC

rg

RG do funcionário

RA_RG

cnpj

CNPJ da filial do funcionário

M0_CGC

dataCnpj

Data da transferência do funcionário

RUM_DATTRA

centroCusto

Centro de custo do funcionário

RA_CC

regimeTrabalho

Categoria do funcionário

RA_CATFUNC

dataNascimento

Data de nascimento do funcionário

RA_NASC

dataCargo

Data alteração da função

RUM_DATFUN

carga_horaria

Carga horária mensal

RA_HRSMES

bate_ponto

Elegibilidade do ponto

Busca no histórico SR9

DT Ahgora: Inclusão na SR9 sobre o ponto do funcionário

data_troca_elegibilidade_ponto

Troca da Elegibilidade do ponto

Busca no histórico SR9

DT Ahgora: Inclusão na SR9 sobre o ponto do funcionário

matricula_chefia

Matrícula chefia

Busca o gestor do departamento do funcionário

nome_chefia

Nome chefia

RA_NOME

email_chefia

E-mail da chefia

RA_EMAIL

codSindicato

Código do sindicato

RA_SINDICA

dataCodSindicato

Data da troca do funcionário de sindicato

Busca no histórico SR9

telefone

Telefone do funcionário

RA_TELEFON

sem_pis

Envio se o funcionário possuí PIS ou não

Validação interna

codInterno

Código Interno do funcionário

Empresa + filial + matricula separados por pipe

matricula_anterior

Matrícula anterior na transferência

Concatenada com Empresa + Filial + RA_MAT anterior

Aviso

title	Importante

O afastamento é único, caso envie o afastamento apenas com data início e posteriormente alterar para enviar a data fim, este afastamento será integrado completo e o registro inicial será substituído no sistema da Ahgora;

Atualizar Status só irá consultar registros com status 'AR' - Aguardando retorno;
Botão Integrar funcionários só ficará habilitado quando houver registro selecionado;
Registros com status 'AR' - Aguardando retorno e 'IN' - Integrados, não serão integrados novamente, para integrar novamente um registro já integrado, ele precisará sofrer alguma alteração no cadastro;
Opção de consultar lote só estará disponível para registros com status diferente de 'NI' - Não integrados;
Após integração, a consulta do retorno com o sistema da Ahgora fica disponível por 1 hora, ou seja, é de extrema importância que após a integração, seja feita a consulta do status para obter o retorno;
de consultar lote só estará disponível para registros com status diferente de 'NI' - Não integrados;
Após integração, a consulta do retorno com o sistema da Ahgora fica disponível por 1 hora, ou seja, é de extrema importância que após a integração, seja feita a consulta do status para obter o retorno;

Alterações no Protheus

Rotinas que irão gravar registros para integração do afastamento na tabela RUM(Lote integração Ahgora):

GPEA240 - Cadastro do Ausências;
GPEM030/GPEM060 - Férias

Ao incluir uma ausência ou alterar um campo no afastamento pertinente para Ahgora, será gerado um registro na tabela de integração.

O registro gerado será do tipo 'A', alteração, porém caso não exista, será criado como inclusão "I".

Aviso

title	Importante

Essas atualizações na tabela de integração só serão executadas caso o parâmetro MV_RHAHGOR estiver habilitado com conteúdo .T.

Card

id	IntegAhgoraExclu
label	Integração Exclusão

Card

id	IntegAhgoraAfast
label	Integração Afastamentos

Inicialmente a tela abre vazia esperando que sejam informados os filtros.

Na tela inicial o filtro é genérico com filial, afastamento exclusão de/até e qual status da integração deseja filtrar.

Para mais filtros, é necessário acessar a opção de 'Filtros Avançados'

Como sugestão, a 'Data Afastamento Exclusão De' vem preenchida com um mês anterior que a data atual e a 'Data Afastamento Exclusão Até' com a data atual.

Filtros de 'Filial' e 'Data Afastamento Exclusão De' são obrigatórios.

Apresentação das Informações

Ao aplicarmos os filtros será apresentada a seguinte tela:

Lista de Afastamentos

Ao obter a lista de afastamentos, temos as colunas:

Status → Correspondente ao status do registro.

- Legenda verde, Tag 'NI' - Integrados

- Legenda azul, Tag 'IN' - Não integrados

- Legenda vermelha, Tag 'CI' - Com Inconsistências

- Legenda laranja, Tag 'AR' - Aguardando Retorno

Matrícula Ahgora → Matrícula composta por Empresa + Filial + Matrícula do funcionário no GPE, campo RA_MAT;
Nome → Nome do funcionário, campo RA_NOME;
Tipo do afastamento → Tipo e descrição do afastamento, campos, R8_TIPOAFA + RCE_DESCRI;
Dt. Início → Inicio do afastamento, campo R8_DATAINI;
Dt. Fim→ Fim do afastamento, campo R8_DATAFIM;
Movimento → Inclusão/AlteraçãoExclusão;
Dt. Movimento → Data da movimentação;

Image RemovedImage Added

O processo de integração e retorno das informações funciona da mesma maneira demostrada na seção 'Integração Funcionários'

Registros que serão enviados na integração

Propriedades	Descrição	Protheus	Observações
matricula	Matrícula Ahgora	Concatenada com Empresa + Filial + RA_MAT
motivo	Tipo do afastamento	R8_TIPOAFA
inicio	Início do afastamento	R8_DATAINI
fim	Fim do afastamento	R8_DATAFIM
cod_interno	Código interno	Empresa + Filial + RA_MAT + R8_SEQ separados por ponto.
operation	Operação	INSDEL	Validação interna

O afastamento é único, caso envie o afastamento apenas com data início e posteriormente alterar para enviar a data fim, este afastamento será integrado completo e o registro inicial será substituído no sistema da Ahgora;

Aviso

title	Importante

Atualizar Status só irá consultar registros com status 'AR' - Aguardando retorno;
Botão Integrar funcionários só ficará habilitado quando houver registro selecionado;
Registros com status 'AR' - Aguardando retorno e 'IN' - Integrados, não serão integrados novamente, para integrar novamente um registro já integrado, ele precisará sofrer alguma alteração no cadastro;
Opção de consultar lote só estará disponível para registros com status diferente de 'NI' - Não integrados;
Após integração, a consulta do retorno com o sistema da Ahgora fica disponível por 1 hora, ou seja, é de extrema importância que após a integração, seja feita a consulta do status para obter o retorno;

Alterações no Protheus

Rotinas que irão gravar registros para integração da exclusão do afastamento na tabela RUM(Lote integração Ahgora):

GPEA240 - Cadastro do Ausências;
GPEM030/GPEM060 - Férias

Ao excluir o afastamento no GPE, será validado se existe o afastamento criado na tabela RUM, e se o mesmo está integrado, caso contrário, essa exclusão não será gerada na tabela de integração;

O registro gerado será do tipo 'E', exclusão.

Aviso

title	Importante

A exclusão só irá ocorrer se de fato o afastamento for excluído do SIGAGPE, ao excluir o afastamento, o registro será criado na tabela de integração RUM, e será possível filtrar ele na tela para o envio dessa exclusão;
Essas atualizações na tabela de integração só serão executadas caso o parâmetro MV_RHAHGOR estiver habilitado com conteúdo .T.

Card

id	schedule
label	Agendamento da Integração/Schedule

Também foi disponibilizada a rotina GPEM943 para ser possível agendar no Schedule a realização da integração e consulta das integrações com Ahgora.

A rotina pode ser cadastrada no Schedule do módulo SIGACFG - Configurador para efetuar a integração automaticamente, conforme exemplo abaixo:

Image Added

Nota

title	Observação

O JOB busca registros na tabela RUM( Lote de Integração Ahgora), caso exista registro com status diferente de 6(Registro enviado e aceito com sucesso), será criado a integração e enviado para Ahgora, na sequencia será consultado o status da integração.

Caso não exista registro a ser enviado, porém exista registro aguardando o retorno, o JOB irá consultar o retorno desse registro com Ahgora.

A rotina automática irá servir para envios do dia a dia, admissões/alterações de funcionários e inclusões/alterações/exclusões de afastamentos.

Para os funcionários, existe uma rotina que faz uma carga inicial na tabela RUM, conforme descrito na seção 'Elegibilidade do ponto'. Ao executar essa rotina, os dados serão gerados na RUM e o JOB se encarregará de enviá-los para a Ahgora.

Para os afastamentos não existe a carga inicial, é necessário utilizar a rotina em POUI para o primeiro envio, na sequencia, ao incluir, alterar ou excluir um afastamento via rotina de ausências, será criado o registro na tabela RUM, consequentemente, o JOB irá integra-lo automaticamente.

Para evitar impacto na performance, recomenda-se que o agendamento seja programado para, no máximo, duas vezes ao dia.

Informações

title	Importante

Para saber mais como realizar o cadastro do schedule, como o agendamento e configuração da recorrência, acesse a documentação do Framework: Schedule - Como agendar a execução de rotinas

É imprescindível que o sistema esteja atualizado com o pacote da expedição contínua do RH, com a atualização do dicionário com a criação da tabela RUM e com os parâmetros(MV_AHGORA1/MV_AHGORA2) de integração com Ahgora configurados.

Exemplo de retorno gerado no console do appserver:

Image Added

O JOB GPEM943 irá seguir a ordem abaixo:

1 - Serão integrados os funcionários contidos na tabela de integração RUM;

2 - Serão consultados o status da integração dos funcionários;

3 - Serão integrados os afastamentos contidos na tabela de integração RUM;

4 - Serão consultados os status da integração dos afastamentos;

5 - Serão integrados as exclusões dos afastamentos contidos na tabela de integração RUM;

6 - Serão consultados os status da integração das exclusões dos afastamentos;

Card

id	IntegAhgoraExclu
label	Integração Exclusão Afastamentos

Inicialmente a tela abre vazia esperando que sejam informados os filtros.

Na tela inicial o filtro é genérico com filial, exclusão de/até e qual status da integração deseja filtrar.

Para mais filtros, é necessário acessar a opção de 'Filtros Avançados'

Como sugestão, a 'Data Exclusão De' vem preenchida com um mês anterior que a data atual e a 'Data Exclusão Até' com a data atual.

Filtros de 'Filial' e 'Data Exclusão De' são obrigatórios.

Apresentação das Informações

Ao aplicarmos os filtros será apresentada a seguinte tela:

Lista de Afastamentos

Ao obter a lista de afastamentos, temos as colunas:

Status → Correspondente ao status do registro.

- Legenda verde, Tag 'NI' - Integrados

- Legenda azul, Tag 'IN' - Não integrados

- Legenda vermelha, Tag 'CI' - Com Inconsistências

- Legenda laranja, Tag 'AR' - Aguardando Retorno

Image Removed

Matrícula Ahgora → Matrícula composta por Empresa + Filial + Matrícula do funcionário no GPE, campo RA_MAT;
Nome → Nome do funcionário, campo RA_NOME;
Tipo do afastamento → Tipo e descrição do afastamento, campos, R8_TIPOAFA + RCE_DESCRI;
Dt. Início → Inicio do afastamento, campo R8_DATAINI;
Dt. Fim→ Fim do afastamento, campo R8_DATAFIM;
Movimento → Exclusão;
Dt. Movimento → Data da movimentação;

Image Removed

O processo de integração e retorno das informações funciona da mesma maneira demostrada na seção 'Integração Funcionários'

Registros que serão enviados na integração

Propriedades

Descrição

Protheus

Observações

matricula

Matrícula Ahgora

Concatenada com Empresa + Filial + RA_MAT

motivo

Tipo do afastamento

R8_TIPOAFA

inicio

Início do afastamento

R8_DATAINI

fim

Fim do afastamento

R8_DATAFIM

cod_interno

Código interno

Empresa + Filial + RA_MAT + R8_SEQ separados por ponto.

operation

Operação

DEL

Validação interna

Aviso

title	Importante

A exclusão só irá ocorrer se de fato o afastamento for excluído do SIGAGPE, ao excluir o afastamento, o registro será criado na tabela de integração RUM, e será possível filtrar ele na tela para o envio dessa exclusão;
Ao excluir o afastamento no GPE, será validado se existe o afastamento criado na tabela RUM, e se o mesmo está integrado, caso contrário, essa exclusão não será gerada na tabela de integração;

Aviso

title	Importante

Totvs custom tabs box items

default	no
referencia	dicionario

Foi efetuado a criação de parâmetros no dicionário SX6, conforme estrutura abaixo:

X6_VAR	X6_TIPO	X6_DESCRIC	Exemplo de preenchimento	Observações
MV_RHAHGOR	L	Habilita a integração de dados do Protheus com do sistesma sistema da Ahgora	.T. ou .F.	Para gerar informações na tabela RUM a partir das inclusões e alterações dos cadastros dos funcionários e afastamentos do GPE, este parâmetro deve ser habilitado
MV_AHGORA1	C	Usuário de acesso do ambiente de integração do sistesma sistema da Ahgora	User de integração do sistema Ahgora disponibilizado pela Ahgora	Para abrir a tela em POUI para integração, este parâmetro deve ser preenchido
MV_AHGORA2	C	Senha de acesso do ambiente de integração do sistesma sistema da Ahgora	Senha de integração do sistema Ahgora disponibilizado pela Ahgora	Para abrir a tela em POUI para integração, este parâmetro deve ser preenchido

Nota

title	Observação

As informações de acesso ao ambiente da Ahgora devem ser solicitadas ao responsável do contrato da Ahgora.

Foi efetuado a criação de tabelas no dicionário SX2, conforme estrutura abaixo:

X2_CHAVE	X2_NOME	X2_MODO	X2_MODOUN	X2_MODOEMP
RUM	Lote de integração Ahgora	C	C	C

Foi efetuado a criação de campos no dicionário SX3 conforme estrutura abaixo:

X3_ARQUIVO	X3_ORDEM	X3_CAMPO	X3_TIPO	X3_TAMANHO	X3_TITULO	X3_DESCRIC
RUM	01	RUM_FILIAL	C	2	Filial	Filial
RUM	02	RUM_FIL	C	2	Filial Reg	Filial do Registro
RUM	03	RUM_MAT	C	6	Matrícula	Matrícula
RUM	04	RUM_CODINT	C	40	Código Inte.	Código Interno
RUM	05	RUM_UNIQUE	C	15	Unique ID	Código do processamento
RUM	06	RUM_SUBUNQ	C	15	Sub Unique	Código Sub Unique
RUM	07	RUM_TIPO	C	1	Tipo API	Tipo API
RUM	08	RUM_STATUS	C	1	Status	Status da integração
RUM	09	RUM_TAB	C	3	Tabela	Tabela que foi manipulada
RUM	10	RUM_KEY	C	200	Chave Reg.	Chave do Registro
RUM	11	RUM_OPER	C	1	Operação	Operação
RUM	12	RUM_TPINT	C	1	Tp. Integra.	Tipo de integração
RUM	13	RUM_DATINT	D	8	Data Integ.	Data Integração
RUM	14	RUM_HORINT	C	8	Hora Integ.	Hora da integração
RUM	15	RUM_LOTE	M	10	Lote	Lote da integração
RUM	16	RUM_RETORN	M	10	Lote Retorno	Lote de retorno
RUM	17	RUM_STAMSN	M	10	Msn. Status	Mensagem do Status
RUM	18	RUM_SEQAFA	C	3	Sequencia	Sequencia Afastamento
RUM	19	RUM_DATAIN	D	8	Dt. Ini. Afa	Data Afastamento
RUM	20	RUM_DATFUN	D	8	Dt. Alt. Fun	Data alteração da Função
RUM	21	RUM_DATTUR	D	8	Dt.Alt Turno	Data alteração do turno
RUM	22	RUM_DATTRA	D	8	Dt. Alt CNPJ	Data alteração CNPJ
RUM	23	RUM_DATMOV	D	8	Dt Movimento	Data do movimento
RUM	24	RUM_USER	C	40	Usuário	Usuário logado

Foi efetuado a criação de índices no dicionário SIX conforme estrutura abaixo:

INDICE	ORDEM	CHAVE
RUM	01	RUM_FILIAL+RUM_TIPO+RUM_TPINT+RUM_CODINT
RUM	02	RUM_FILIAL+RUM_TIPO+RUM_UNIQUE+RUM_SUBUNQ
RUM	03	RUM_FILIAL+RUM_FIL+RUM_MAT+RUM_TIPO+RUM_CODINT
RUM	04	RUM_FILIAL+RUM_TAB+RUM_OPER+RUM_KEY
RUM	05	RUM_FILIAL+RUM_TIPO+RUM_SUBUNQ+RUM_UNIQUE
RUM	06	RUM_FILIAL+RUM_KEY
RUM	07	RUM_FILIAL+RUM_FIL+RUM_MAT+DTOS(RUM_DATINT)+RUM_HORINT+RUM_CODINT
RUM	08	RUM_FILIAL+RUM_TIPO+RUM_OPER+DTOS(RUM_DATMOV)+RUM_CODINT
RUM	09	RUM_FILIAL+RUM_OPER+DTOS(RUM_DATAIN)+RUM_CODINT

Foi efetuado a criação de relacionamento no dicionário SX9 conforme estrutura abaixo:

X9_DOM	X9_IDENT	X9_CDOM	X9_EXPDOM	X9_EXPCDOM
SRA	001	RUM	RA_MAT	RUM_MAT

Aviso

title	Importante

A integração depende da aplicação da atualização liberada no pacote de expedição do módulo RH a partir de 2004/0910/2024 e da execução do UPDDISTR com o dicionário diferencial para os releases iguais ou superiores a versão 12.1.033;

Totvs custom tabs box items

default	no
referencia	tech

Informações Técnicas da API

Este detalhamento tem como objetivo registrar os endpoints da interface da integração com Ahgora, desenvolvida utilizando PO-UI.

Deck of Cards

id	IntegracaoAhgora

Card

id	IntegAhgoraLista
label	Integração Funcionário

Objetivo: Busca dos dados para listagem dos funcionários e envio dos funcionários selecionados para o back-end.

Tipo de requisição: GET/POST

Endpoint: /api/rh/v1/ahgora/funcionarios

Get:

Query Params:

Nome	Descrição	Tipo	Obrigatório	Exemplo
page	Número da página	number	Sim	1
pageSize	Tamanho da página	number	Sim	100
dataAdmissaoDe	Data de Admissão De	string	Sim	"2023-01-02T16:37:02-03:00"
dataAdmissaoAte	Data de demissão do funcionário Até	string	Não	"2024-01-02T16:37:02-03:00"
branchCode	Filial (Multi Valores separados por vírgula)	string	Sim	“D MG 01,D MG 02”
matCode	Matrícula De	string	Não	000001
matCodeAte	Matrícula Até	string	Não	000004
situacao	Situação do funcionário (Multi Valores separados por vírgula)	string	Não	N,A
categoria	Categoria do funcionário (Multi Valores separados por vírgula)	string	Não	M,E
tipostatus	Tipo do status (Multi Valores separados por vírgula)	string	Não	0-Não Integrados; 3-Com Inconsistências; 4-Aguardando Retorno; 6-Integrados;
codCC	Centro de custo De	string	Não	001
codCCAte	Centro de Custo Até	string	Não	001
codFuncao	Função De	string	Não	001
codFuncaoAte	Função Até	string	Não	001
codDepto	Departamento De	string	Não	000000061
codDeptoAte	Departamento Até	string	Não	000000061
turnoCode	Turno De	string	Não	001
turnoCodeAte	Turno Até	string	Não	001

Estrutura de Retorno:

Campo	Tipo	Exemplo
statusAhgora(obrigatório)	string	NI(Não Integrado), IN(Integrado), CI(Com inconsistência), AR(Aguardando retorno)
matricula(obrigatório)	string	0101000001
dataAdmissao(obrigatório)	string	2024-01-01
dataDemissao	string	""
escala_padrao	string	001
cargo	string	001 - BIOMEDICO ASSIST. II
departamento	string	001 - Departamento RH
centroCusto	string	001 - CC Tecnologia
codInterno(obrigatório)	string	01\|01\|040924
tpMovimento(obrigatório)	string	I(Inclusão), A(Alteração)
dtMovimento(obrigatório)	string	2024-09-05

Exemplo de Requisição:

GET: api/rh/v1/ahgora/funcionarios?page=1&pageSize=100&dataAdmissaoDe=2024-01-01T17:29:41-03:00&dataAdmissaoAte=2024-09-05T17:29:41-03:00&branchCode=01,02&situacao=

N,A&categoria=M,E&tipostatus=0,6&codCC=001%20%20%20%20%20%20&codCCAte=001%20%20%20%20%20%20&codFuncao=001%20%20&codFuncaoAte=001%20%20&turnoCode=001&turnoCodeAte=001

Se atentar com a paginação.

Expandir

title	Exemplo de retorno

{
"items": [
{
"statusAhgora": "NI",
"matricula": "0101040924",
"nome": "John Doe",
"dataAdmissao": "2024-01-01",
"dataDemissao": "",
"escala_padrao": "001",
"cargo": "001 - BIOMEDICO ASSIST. II",
"departamento": "",
"centroCusto": "001 - CC Tecnologia da Informac",
"codInterno": "01|01|040924",
"tpMovimento": "I",
"dtMovimento": "2024-09-05"
},
{
"statusAhgora": "NI",
"matricula": "0101999557",
"nome": "Jane Doe",
"dataAdmissao": "2024-01-01",
"dataDemissao": "",
"escala_padrao": "001",
"cargo": "001 - BIOMEDICO ASSIST. II",
"departamento": "",
"centroCusto": "001 - CC Tecnologia da Informac",
"codInterno": "01|01|999557",
"tpMovimento": "I",
"dtMovimento": "2024-09-05"
}
],
"hasNext": false
}

Post: /api/rh/v1/ahgora/funcionarios

Nome	Descrição	Tipo	Obrigatório	Exemplo
codInterno	Código interno do funcionário	string	Sim	01\|01\|210824
dtMovimento	Data do movimento	string	Sim	2024-09-05
tpMovimento	Tipo do movimento	string	Sim	I(Inclusão)

A partir do filtro realizado, ao clicar em integrar funcionário, os dados serão enviados para o back-end.

Expandir

title	Exemplo do post

{
"items":
[
{
"codInterno":"01|01|210824",
"tpMovimento":"I",
"dtMovimento":"2024-09-05"
}
]
}

Com os dados postados, o back-end se encarregará de montar o body para requisição de envio para o Ahgora: https://api.ahgora.com.br/people

Expandir

title	Exemplo de envio para Ahgora

[
{
"matricula": "0101210824",
"nome": "John Doe",
"pis": "",
"matricula_esocial": "010121082420240821162913 ",
"dataAdmissao": "2024-01-01",
"dataDemissao": "",
"localizacoes": "",
"escala_padrao": "001",
"lastChangeDefaultSchedule": "",
"tipo_escala": "",
"ctps": " ",
"cargo": "001 - BIOMEDICO ASSIST. II",
"departamento": "",
"sexo": "M",
"email": " ",
"cpf": " ",
"rg": " ",
"cnpj": "53113791000122",
"dataCnpj": "",
"centroCusto": "001",
"regimeTrabalho": "CLT",
"dataNascimento": "1990-01-01",
"dataCargo": "",
"carga_horaria": 220,
"bate_ponto": "Ponto Obrigatorio",
"data_troca_elegibilidade_ponto": "2024-01-01",
"matricula_chefia": "",
"nome_chefia": "",
"email_chefia": "",
"codSindicato": "01",
"dataCodSindicato": "",
"telefone": " ",
"sem_pis": true,
"codInterno": "01|01|210824",
"matricula_anterior": ""
}
]

Retorno do código unique de processamento retornado pela Ahgora

Expandir

title	Rertorno do unique criado pela Ahgora

{
"company":"a148176",
"message":"Employee's Integration on progress",
"unique":"b6ca283f"
}

Devolver o retorno para o POUI com o status da integração para que seja atualizado a lista, nesse caso 'AR' (Aguardando retorno), pois ainda não foi feita a consulta do unique.

Estrutura de Retorno:

Campo	Tipo	Exemplo
codInterno	string	01\|01\|210824
statusAhgora	string	AR

Expandir

title	Rertorno da integração para o POUI

{
"items":
[
{
"codInterno":"01|01|210824",
"statusAhgora":"AR"
}
]
}

Card documentos

Informacao	Com o código unique em mãos, será necessário consultar o status do processamento na Ahgora. Pode ser feito após o envio antes do retorno para o POUI ou através do botão 'Atualizar Status' que está disponível na tela
Titulo	Importante

Para o retorno de erro, seguir a estrutura abaixo.

Campo	Tipo
code	number
message	string
detailedMessage	string
type	string (“error”, “warning”, “success”)

Expandir

title	Exemplo de retorno

{
"code": 500,
"detailedMessage": "",
"message": "Internal Server Error",
"type": "error"
}

Card

id	IntegAhgoraAfast
label	Integração Afastamento

Objetivo: Busca dos dados para listagem dos afastamentos e envio dos afastamentos selecionados para o back-end.

Tipo de requisição: GET/POST

Endpoint: /api/rh/v1/ahgora/afastamentos

Get:

Query Params:

Nome	Descrição	Tipo	Obrigatório	Exemplo
page	Número da página	number	Sim	1
pageSize	Tamanho da página	number	Sim	100
dataAfastDe	Data Afastamento De	string	Sim	"2019-01-02T16:37:02-03:00"
dataAfastAte	Data Afastamento Até	string	Não	"2024-01-02T16:37:02-03:00"
branchCode	Filial (Multi Valores separados por vírgula)	string	Sim	"01,02"
matCode	Matrícula De	string	Não	000004
matCodeAte	Matrícula Até	string	Não	000004
situacao	Situação do funcionário (Multi Valores separados por vírgula)	string	Não	N,A
categoria	Categoria do funcionário (Multi Valores separados por vírgula)	string	Não	M,E
tipostatus	Tipo do status (Multi Valores separados por vírgula)	string	Não	0,6
codCC	Centro de custo De	string	Não	001
codCCAte	Centro de Custo Até	string	Não	001
codFuncao	Função De	string	Não	001
codFuncaoAte	Função Até	string	Não	001
codDepto	Departamento De	string	Não	000000061
codDeptoAte	Departamento Até	string	Não	000000061
turnoCode	Turno De	string	Não	001
turnoCodeAte	Turno Até	string	Não	001

Estrutura de Retorno:

Campo	Tipo	Exemplo
statusAhgora(obrigatório)	string	NI(Não Integrado), IN(Integrado), CI(Com inconsistência), AR(Aguardando retorno)
matricula(obrigatório)	string	0101000001
nome	string	John Doe
motivo	string	004 - Afastamento Temporário por Doença
inicio	string	2019-01-01
fim	string	2019-01-02
cod_interno(obrigatório)	string	01.01.000004.001
tpMovimento(obrigatório)	string	I(Inclusão)
dtMovimento(obrigatório)	string	2024-09-06

Exemplo de Requisição:

GET: api/rh/v1/ahgora/afastamentos?page=1&pageSize=100&dataAfastDe=2000-01-01T08:39:02-03:00&dataAfastAte=2024-09-06T08:39:02-03:00&branchCode=01&

matCode=&matCodeAte=&situacao=&categoria=&tipostatus=&codCC=&codCCAte=&codFuncao=&codFuncaoAte=&codDepto=&codDeptoAte=&turnoCode=&turnoCodeAte=

Se atentar com a paginação.

Expandir

title	Exemplo de retorno

{
"items": [
{
"statusAhgora": "NI",
"matricula": "0101000004",
"nome": "John Doe",
"motivo": "004 - Afastamento Temporário por Doença",
"inicio": "2019-01-01",
"fim": "2019-01-02",
"cod_interno": "01.01.000004.001",
"tpMovimento": "I",
"dtMovimento": "2024-09-06"
},
{
"statusAhgora": "NI",
"matricula": "0101000962",
"nome": "John Doe",
"motivo": "004 - Afastamento Temporário por Doença",
"inicio": "2023-01-01",
"fim": "2023-01-02",
"cod_interno": "01.01.000962.003",
"tpMovimento": "I",
"dtMovimento": "2024-09-06"
}
],
"hasNext": true
}

Post: /api/rh/v1/ahgora/afastamentos

Nome	Descrição	Tipo	Obrigatório	Exemplo
cod_interno	Código interno do afastamento	string	Sim	01.01.000004.001
dtMovimento	Data do movimento	string	Sim	2024-09-06
tpMovimento	Tipo do movimento	string	Sim	I(Inclusão)

A partir do filtro realizado, ao clicar em integrar afastamento, os dados serão enviados para o back-end.

Expandir

title	Exemplo do post

{
"items":
[
{
"cod_interno":"01.01.000004.001",
"tpMovimento":"I",
"dtMovimento":"2024-09-06"
}
]
}

Com os dados postados, o back-end se encarregará de montar o body para requisição de envio para o Ahgora: https://api.ahgora.com.br/absences

Obs* Caso não exista data fim, enviar uma fictícia, exemplo: 31/12/2099

Expandir

title	Exemplo de envio para Ahgora

[
{
"matricula": "0101000004",
"motivo": "004",
"inicio": "2019-01-01",
"fim": "2019-01-02",
"cod_interno": "01.01.000004.001",
"operation": "INS"
}
]

Retorno do código unique de processamento retornado pela Ahgora

Expandir

title	Rertorno do unique criado pela Ahgora

{
"company":"a148176",
"message":"Employee's Integration on progress",
"unique":"c5ga345h"
}

Devolver o retorno para o POUI com o status da integração para que seja atualizado a lista, nesse caso 'AR' (Aguardando retorno), pois ainda não foi feita a consulta do unique.

Estrutura de Retorno:

Campo	Tipo	Exemplo
codInterno	string	01.01.000004.001
statusAhgora	string	AR

Expandir

title	Rertorno da integração para o POUI

{
"items":
[
{
"codInterno":"01.01.000004.001",
"statusAhgora":"AR"
}
]
}

Card documentos

Informacao	Com o código unique em mãos, será necessário consultar o status do processamento na Ahgora. Pode ser feito após o envio antes do retorno para o POUI ou através do botão 'Atualizar Status' que está disponível na tela
Titulo	Importante

Para o retorno de erro, seguir a estrutura abaixo.

Campo	Tipo
code	number
message	string
detailedMessage	string
type	string (“error”, “warning”, “success”)

Expandir

title	Exemplo de retorno

{
"code": 500,
"detailedMessage": "",
"message": "Internal Server Error",
"type": "error"
}

Card

id	IntegAhgoraExclu
label	Integração Exclusão Afastamento

Objetivo: Busca dos dados para listagem dos afastamentos excluídos e envio dos afastamentos excluídos selecionados para o back-end.

Tipo de requisição: GET/POST

Endpoint: /api/rh/v1/ahgora/afastamentos/exclusao

Get:

Query Params:

Nome	Descrição	Tipo	Obrigatório	Exemplo
page	Número da página	number	Sim	1
pageSize	Tamanho da página	number	Sim	100
dataExcDe	Data Exclusão De	string	Sim	"2019-01-02T16:37:02-03:00"
dataExcAte	Data Exclusão Até	string	Não	"2024-01-02T16:37:02-03:00"
branchCode	Filial (Multi Valores separados por vírgula)	string	Sim	"01,02"
matCode	Matrícula De	string	Não	000002
matCodeAte	Matrícula Até	string	Não	000002
situacao	Situação do funcionário (Multi Valores separados por vírgula)	string	Não	N,A
categoria	Categoria do funcionário (Multi Valores separados por vírgula)	string	Não	M,E
tipostatus	Tipo do status (Multi Valores separados por vírgula)	string	Não	0,6
codCC	Centro de custo De	string	Não	001
codCCAte	Centro de Custo Até	string	Não	001
codFuncao	Função De	string	Não	001
codFuncaoAte	Função Até	string	Não	001
codDepto	Departamento De	string	Não	000000061
codDeptoAte	Departamento Até	string	Não	000000061
turnoCode	Turno De	string	Não	001
turnoCodeAte	Turno Até	string	Não	001

Estrutura de Retorno:

Campo	Tipo	Exemplo
statusAhgora(obrigatório)	string	NI(Não Integrado), IN(Integrado), CI(Com inconsistência), AR(Aguardando retorno)
matricula(obrigatório)	string	0101000001
nome	string	John Doe
motivo	string	004 - Afastamento Temporário por Doença
inicio	string	2019-01-01
fim	string	2019-01-02
cod_interno(obrigatório)	string	01.01.000004.001
tpMovimento(obrigatório)	string	E(Inclusão)
dtMovimento(obrigatório)	string	2024-09-06

Exemplo de Requisição:

GET: api/rh/v1/ahgora/afastamentos/exclusao?page=1&pageSize=100&dataExcDe=2000-01-01T09:03:57-03:00&dataExcAte=2024-09-06T09:03:57-03:00&

branchCode=01&matCode=&matCodeAte=&situacao=&categoria=&tipostatus=&codCC=&codCCAte=&codFuncao=&codFuncaoAte=&codDepto=&codDeptoAte=&turnoCode=&turnoCodeAte=

Se atentar com a paginação.

Expandir

title	Exemplo de retorno

{
"items": [
{
"statusAhgora": "NI",
"matricula": "0101000002",
"nome": "Jane Doe",
"motivo": "004 - Afastamento Temporário por Doença",
"inicio": "2024-08-01",
"fim": "2024-08-10",
"cod_interno": "01.01.000002.001",
"tpMovimento": "E",
"dtMovimento": "2024-08-29"
}
],
"hasNext": false
}

Post: /api/rh/v1/ahgora/afastamentos/exclusao

Nome	Descrição	Tipo	Obrigatório	Exemplo
cod_interno	Código interno do afastamento	string	Sim	01.01.000002.001
dtMovimento	Data do movimento	string	Sim	2024-08-29
tpMovimento	Tipo do movimento	string	Sim	E(Exclusão)

A partir do filtro realizado, ao clicar em integrar afastamento, os dados serão enviados para o back-end.

Expandir

title	Exemplo do post

{
"items":
[
{
"cod_interno":"01.01.000002.001",
"tpMovimento":"E",
"dtMovimento":"2024-08-29"
}
]
}

Com os dados postados, o back-end se encarregará de montar o body para requisição de envio para o Ahgora: https://api.ahgora.com.br/absences

Expandir

title	Exemplo de envio para Ahgora

Poderá ser enviado dessa forma

[
{
"matricula": "0101000002",
"motivo": "004",
"inicio": "2024-08-01",
"fim": "2024-08-10",
"cod_interno": "01.01.000002.001",
"operation": "DEL"
}
]

Ou enviar apenas o código interno e a operação

[
{
"cod_interno": "01.01.000002.001",
"operation": "DEL"
}
]

Retorno do código unique de processamento retornado pela Ahgora

Expandir

title	Rertorno do unique criado pela Ahgora

{
"company":"a148176",
"message":"Employee's Integration on progress",
"unique":"d6jb378d"
}

Devolver o retorno para o POUI com o status da integração para que seja atualizado a lista, nesse caso 'AR' (Aguardando retorno), pois ainda não foi feita a consulta do unique.

Estrutura de Retorno:

Campo	Tipo	Exemplo
codInterno	string	01.01.000002.001
statusAhgora	string	AR

Expandir

title	Rertorno da integração para o POUI

{
"items":
[
{
"codInterno":"01.01.000002.001",
"statusAhgora":"AR"
}
]
}

Card documentos

Informacao	Com o código unique em mãos, será necessário consultar o status do processamento na Ahgora. Pode ser feito após o envio antes do retorno para o POUI ou através do botão 'Atualizar Status' que está disponível na tela
Titulo	Importante

Para o retorno de erro, seguir a estrutura abaixo.

Campo	Tipo
code	number
message	string
detailedMessage	string
type	string (“error”, “warning”, “success”)

Expandir

title	Exemplo de retorno

{
"code": 500,
"detailedMessage": "",
"message": "Internal Server Error",
"type": "error"
}

Card

id	status
label	Status/Consulta

Totvs custom tabs box items

default	no
referencia	status

Deck of Cards

id	Status/Consulta

Card

id	status
label	Atualizar Status

Objetivo: Obter o status da integração

Tipo de requisição: POST

Endpoint: /api/rh/v1/ahgora/status/

Query Params:

Campo	Descrição	Tipo	Obrigatório	Exemplo
cApi	Tipo da API: 1-People; 2-Absences;	string	SIM	1

Ao selecionar os registros com status 'Aguardando retorno' e clicar no botão atualizar Status, os registros serão enviados para o back-end.

Exemplo de Requisição:

POST: api/rh/v1/ahgora/status/?cApi=1

Expandir

title	Exemplo do post

{
"items": [
{
"codInterno":"01|01|000002"
}
]
}

POST: api/rh/v1/ahgora/status/?cApi=2

Expandir

title	Exemplo de retorno

{
"items":
[
{
"codInterno":"01.01.000002.001"
}
]
}

Com o código interno em mãos, será necessário encontrar o código unique gravado anteriormente para fazer o get na API da Ahgora: https://api.ahgora.com.br/v2/process/?unique=0b8ef0cc

Retorno do status da Ahgora para o unique pesquisado.

Veja que nesse caso o retorno veio com 2 erros, que devem ser gravados para posterior consulta na tela.

Os erros precisam ser gravados separados por pipe quando existir mais de um, exemplo: Centro de custo inválido | CNPJ inválido

Expandir

title	Rertorno do status da integração pela Ahgora

{
"data": {
"errors": [
{
"identifier": "0101000004",
"message": [
"Centro de custo inválido",

"CNPJ inválido"

]
}
]
},
"company": "a148176",
"unique": "0b8ef0cc",
"status": "error",
"progress": {
"done": "1",
"total": "1"
}
}

Estrutura de Retorno para o POUI:

Campo	Tipo
codInterno	string
statusAhgora	string

Como o retorno está com inconsistência, devolvo com status 'CI'

Expandir

title	Exemplo de retorno

{
"items": [
{
"codInterno": "01.01.000004.001",
"statusAhgora":"CI"
}
]
}

Para o retorno de erro, seguir a estrutura abaixo.

Campo	Tipo
code	number
message	string
detailedMessage	string
type	string (“error”, “warning”, “success”)

Expandir

title	Exemplo de retorno

{
"code": 500,
"detailedMessage": "",
"message": "Internal Server Error",
"type": "error"
}

Card

id	registro
label	Status do registro

Objetivo: Consulta status do registro com inconsistência posicionado na linha

Tipo de requisição: GET

Endpoint: /api/rh/v1/ahgora/status/:codInterno

Query Params:

Campo	Descrição	Tipo	Obrigatório	Exemplo
cApi	Tipo da API: 1-People; 2-Absences;	string	SIM	1

Estrutura de Retorno:

Campo	Tipo
status	string

Exemplo de Requisição:

GET: api/rh/v1/ahgora/status/010100004?cApi=1

Buscamos o status do registro com inconsistência, no retorno da Ahgora caso exista mais de um erro deve ser separado por pipe conforme explicado na seção 'Atualizar Status'

Expandir

title	Exemplo de retorno

{
"items": [
{
"status":"Centro de custo inválido | CNPJ inválido"
}
]
}

O pipe é necessário para a quebra de linha e visualização em tela conforme imagem abaixo.

Obs* A numeração é feita pelo POUI.

Para o retorno de erro, seguir a estrutura abaixo.

Campo	Tipo
code	number
message	string
detailedMessage	string
type	string (“error”, “warning”, “success”)

Expandir

title	Exemplo de retorno

{
"code": 500,
"detailedMessage": "",
"message": "Internal Server Error",
"type": "error"
}

Card

id	lote
label	Consulta Lote

Objetivo: Consulta do lote de envio

Tipo de requisição: GET

Endpoint: /api/rh/v1/ahgora/lote/:codInterno

Query Params:

Campo	Descrição	Tipo	Obrigatório	Exemplo
cApi	Tipo da API: 1-People; 2-Absences;	string	SIM	2

Estrutura de Retorno:

Campo	Tipo
lote	string
data	string
hora	string

Exemplo de Requisição:

GET: api/rh/v1/ahgora/lote/01.01.125803.001?cApi=2

Passamos o código interno do funcionário e o tipo da API para que possam encontrar o lote salvo anteriormente para o registro.

Expandir

title	Exemplo de retorno

{
"items": [
{
"lote": "[{\"matricula\": \"0101125803\",\"motivo\": \"001\",\"inicio\": \"2024-01-29\",\"fim\": \"2024-02-17\",\"cod_interno\": \"01.01.125803.001\",\"operation\": \"INS\"}]",
"data": "2024-08-30",
"hora": "19:44:02"
}
]
}

Para o retorno de erro, seguir a estrutura abaixo.

Campo	Tipo
code	number
message	string
detailedMessage	string
type	string (“error”, “warning”, “success”)

Expandir

title	Exemplo de retorno

{
"code": 500,
"detailedMessage": "",
"message": "Internal Server Error",
"type": "error"
}

Card

id	filtros
label	Filtros

Totvs custom tabs box items

default	no
referencia	filtros

Deck of Cards

id	Filtros

Card

id	branches
label	Branches

Objetivo: Listagem de Filiais

Tipo de requisição: GET

Endpoint: /api/rh/v1/ahgora/branches

Query Params:

Campo	Descrição	Tipo	Obrigatório	Exemplo
page	Número da página	number	SIM	1
pageSize	Tamanho da página	numer	SIM	50
filter	Campo automático do lookup. Pode filtrar o código ou nome da filial	string	Não	“Filial X”

Estrutura de Retorno:

Para conseguirmos abranger todas as áreas, utilizamos a nomenclatura abaixo.

Campo	Tipo
branchCode	string
branchName	string

Exemplo de Requisição:

GET: api/rh/v1/ahgora/branches?filter=&page=1&pageSize=50

Expandir

title	Exemplo de retorno

{
"items": [
{
"branchCode": "01",
"branchName": "Matriz"
},
{
"branchCode": "02",
"branchName": "Suporte-Suporte"
},
{
"branchCode": "03",
"branchName": "Santos"
},
{
"branchCode": "04",
"branchName": "São Vicente"
}
],
"hasNext": false
}

É possível também digitar no campo sem entrar no lookup para buscar uma filial.

Get: api/rh/v1/ahgora/branches/01

Expandir

title	Exemplo de retorno

{
"items": [
{
"branchCode": "01",
"branchName": "Matriz"
}
]
}

Para o retorno de erro, seguir a estrutura abaixo.

Campo	Tipo
code	number
message	string
detailedMessage	string
type	string (“error”, “warning”, “success”)

Expandir

title	Exemplo de retorno

{
"code": 500,
"detailedMessage": "",
"message": "Internal Server Error",
"type": "error"
}

Card

id	matricula
label	Matrícula

Objetivo: Listagem das Matrículas

Tipo de requisição: GET

Endpoint: /api/rh/v1/ahgora/matricula

Query Params:

Campo	Descrição	Tipo	Obrigatório	Exemplo
page	Número da página	number	SIM	1
pageSize	Tamanho da página	numer	SIM	50
filter	Campo automático do lookup. Pode filtrar a matrícula	string	Não	“Matrícula X”
branchCode	Código da filial que está no filtro	string	Não	04

Obs* O filtro da filial é obrigatório, ele vai estar no filtro da matrícula caso queira retornar apenas as matrículas das filiais selecionadas.

Estrutura de Retorno:

Para conseguirmos abranger todas as áreas, utilizamos a nomenclatura abaixo.

Campo	Tipo
branchCode	string
branchName	string

Exemplo de Requisição:

GET: api/rh/v1/ahgora/matricula?filter=&page=1&pageSize=50&branchCode=04

Expandir

title	Exemplo de retorno

Como passei a filial 04 que está no filtro, optei por carregar apenas matrículas dessa filial

{
"items": [
{
"filMat": "04",
"matCode": "000001",
"matName": "John Doe"
},
{
"filMat": "04",
"matCode": "152062",
"matName": "Jane Doe"
}
],
"hasNext": false
}

Para o retorno de erro, seguir a estrutura abaixo.

Campo	Tipo
code	number
message	string
detailedMessage	string
type	string (“error”, “warning”, “success”)

Expandir

title	Exemplo de retorno

{
"code": 500,
"detailedMessage": "",
"message": "Internal Server Error",
"type": "error"
}

Card

id	turno
label	Turno

Objetivo: Listagem dos Turnos

Tipo de requisição: GET

Endpoint: /api/rh/v1/ahgora/turno

Query Params:

Campo	Descrição	Tipo	Obrigatório	Exemplo
page	Número da página	number	SIM	1
pageSize	Tamanho da página	numer	SIM	50
filter	Campo automático do lookup. Pode filtrar o turno	string	Não	“Turno X”
branchCode	Código da filial que está no filtro	string	Não	02

Obs* O filtro da filial é obrigatório, ele vai estar no filtro do turno caso queira retornar apenas os turnos das filiais selecionadas.

Estrutura de Retorno:

Campo	Tipo
filTurno	string
turnoCode	string
turnoDesc	string

Exemplo de Requisição:

GET: api/rh/v1/ahgora/turno?filter=&page=1&pageSize=50&branchCode=02

Expandir

title	Exemplo de retorno

Como passei a filial 02 que está no filtro, optei por carregar apenas os turnos dessa filial

{
"items": [
{
"filTurno": "02",
"turnoCode": "001",
"turnoDesc": "001"
}
],
"hasNext": false
}

Para o retorno de erro, seguir a estrutura abaixo.

Campo	Tipo
code	number
message	string
detailedMessage	string
type	string (“error”, “warning”, “success”)

Expandir

title	Exemplo de retorno

{
"code": 500,
"detailedMessage": "",
"message": "Internal Server Error",
"type": "error"
}

Card

id	ccusto
label	Centro de Custo

Objetivo: Listagem dos Centros de Custo

Tipo de requisição: GET

Endpoint: /api/rh/v1/ahgora/ccusto

Query Params:

Campo	Descrição	Tipo	Obrigatório	Exemplo
page	Número da página	number	SIM	1
pageSize	Tamanho da página	numer	SIM	50
filter	Campo automático do lookup. Pode filtrar o C.Custo	string	Não	“CCusto X”
branchCode	Código da filial que está no filtro	string	Não	02

Obs* O filtro da filial é obrigatório, ele vai estar no filtro do centro de custo caso queira retornar apenas os centros de custo das filiais selecionadas.

Estrutura de Retorno:

Campo	Tipo
filCC	string
codCC	string
ccDesc	string

Exemplo de Requisição:

GET: api/rh/v1/ahgora/ccusto?filter=&page=1&pageSize=10&branchCode=02

Expandir

title	Exemplo de retorno

Como a tabela de Centro de Custo é compartilhada, mesmo com a filial, eu retorno todos

{
"items": [
{
"filCC": " ",
"codCC": "000000003",
"ccDesc": "03"
},
{
"filCC": " ",
"codCC": "000000010",
"ccDesc": "010"
},
{
"filCC": " ",
"codCC": "000000022",
"ccDesc": "22"
},
{
"filCC": " ",
"codCC": "00001 ",
"ccDesc": "TESTE TITULO"
},
{
"filCC": " ",
"codCC": "012 ",
"ccDesc": "CONC 012"
}
],
"hasNext": true
}

Para o retorno de erro, seguir a estrutura abaixo.

Campo	Tipo
code	number
message	string
detailedMessage	string
type	string (“error”, “warning”, “success”)

Expandir

title	Exemplo de retorno

{
"code": 500,
"detailedMessage": "",
"message": "Internal Server Error",
"type": "error"
}

Card

id	funcao
label	Função

Objetivo: Listagem das Funções

Tipo de requisição: GET

Endpoint: /api/rh/v1/ahgora/funcao

Query Params:

Campo	Descrição	Tipo	Obrigatório	Exemplo
page	Número da página	number	SIM	1
pageSize	Tamanho da página	numer	SIM	50
filter	Campo automático do lookup. Pode filtrar o C.Custo	string	Não	“Funcao X”
branchCode	Código da filial que está no filtro	string	Não	02

Obs* O filtro da filial é obrigatório, ele vai estar no filtro da função caso queira retornar apenas as funções das filiais selecionadas.

Estrutura de Retorno:

Campo	Tipo
filFuncao	string
codFuncao	string
funcaoDesc	string

Exemplo de Requisição:

GET: api/rh/v1/ahgora/funcao?filter=&page=1&pageSize=10&branchCode=02

Expandir

title	Exemplo de retorno

Como passei a filial 02 que está no filtro, optei por carregar apenas as funções dessa filial

{
"items": [
{
"filFuncao": "02",
"codFuncao": "00001",
"funcaoDesc": "CP038"
},
{
"filFuncao": "02",
"codFuncao": "00002",
"funcaoDesc": "65456"
}
],
"hasNext": false
}

Para o retorno de erro, seguir a estrutura abaixo.

Campo	Tipo
code	number
message	string
detailedMessage	string
type	string (“error”, “warning”, “success”)

Expandir

title	Exemplo de retorno

{
"code": 500,
"detailedMessage": "",
"message": "Internal Server Error",
"type": "error"
}

Card

id	depto
label	Departamento

Objetivo: Listagem dos Departamentos

Tipo de requisição: GET

Endpoint: /api/rh/v1/ahgora/departamento

Query Params:

Campo	Descrição	Tipo	Obrigatório	Exemplo
page	Número da página	number	SIM	1
pageSize	Tamanho da página	numer	SIM	50
filter	Campo automático do lookup. Pode filtrar o C.Custo	string	Não	“Departamento X”
branchCode	Código da filial que está no filtro	string	Não	02

Obs* O filtro da filial é obrigatório, ele vai estar no filtro da função caso queira retornar apenas os departamentos das filiais selecionadas.

Estrutura de Retorno:

Campo	Tipo
filDepto	string
codDepto	string
deptoDesc	string

Exemplo de Requisição:

GET: api/rh/v1/ahgora/departamento?filter=&page=1&pageSize=10&branchCode=02

Expandir

title	Exemplo de retorno

Como passei a filial 02 que está no filtro, optei por carregar apenas os departamentos dessa filial

{
"items": [
{
"filDepto": "02",
"codDepto": "000000060",
"deptoDesc": "DEP MAT 002042"
},
{
"filDepto": "02",
"codDepto": "000000061",
"deptoDesc": "DEP DELETADO"
},
{
"filDepto": "02",
"codDepto": "0002 ",
"deptoDesc": "Depto Vendas"
}
],
"hasNext": false
}

Para o retorno de erro, seguir a estrutura abaixo.

Campo	Tipo
code	number
message	string
detailedMessage	string
type	string (“error”, “warning”, “success”)

Expandir

title	Exemplo de retorno

{
"code": 500,
"detailedMessage": "",
"message": "Internal Server Error",
"type": "error"
}

Card

id	sitcateg
label	Situação/Categoria

Objetivo: Listagem da situação do funcionário e categoria

Tipo de requisição: GET

Endpoint: /api/rh/v1/ahgora/opcoes

Obs* Sempre será retornado os dois conjuntos de dados na requisição, após a primeira requisição, os dois conjuntos ficaram em memória para consulta;

Estrutura de Retorno:

Para o retorno, utilizamos a forma abaixo.

Campo	Tipo
label	string
value	string

Exemplo de Requisição:

GET: /api/rh/v1/ahgora/opcoes

O retorno precisa ser uma lista com a propriedade 'items', com os dois arrays 'SitOptions' para a situação e 'catOptions' para as categorias.

Expandir

title	Exemplo de retorno

{
"items": {
"sitOptions": [
{
"value": "N",
"label": "SITUACAO NORMAL"
},
{
"value": "A",
"label": "AFASTADO TEMP."
},
{
"value": "D",
"label": "DEMITIDO"
},
{
"value": "F",
"label": "FERIAS"
}
],
"catOptions": [
{
"value": "A",
"label": "AUTONOMO"
},
{
"value": "C",
"label": "COMISSIONADO"
},
{
"value": "D",
"label": "DIARISTA"
},
{
"value": "E",
"label": "ESTAGIARIO MENSALISTA"
},
{
"value": "M",
"label": "MENSALISTA"
}
]
}
}

Para o retorno de erro, seguir a estrutura abaixo.

Campo	Tipo
code	number
message	string
detailedMessage	string
type	string (“error”, “warning”, “success”)

Expandir

title	Exemplo de retorno

{
"code": 500,
"detailedMessage": "",
"message": "Internal Server Error",
"type": "error"
}

04. DEMAIS INFORMAÇÕES

05. ASSUNTOS RELACIONADOS

...

Totvs custom tabs box items

default	no
referencia	doc

Ahgora: API - Resultados

...

Atualizador de dicionário e base de dados - UPDDISTR

...

Schedule - Como agendar a execução de rotinas

.

Templatedocumentos

Árvore de páginas

Versões comparadas

Versão antiga 29

Nova versão 50

Chave

CONTEÚDO

Menu - Rotina GPEM929

Integração e Opções em tela

Apresentação das Informações

Lista de Funcionários

Apresentação das Informações

Lista de Afastamentos

Apresentação das Informações

Lista de Funcionários

Apresentação das Informações

Lista de Afastamentos

Apresentação das Informações

Lista de Afastamentos

Informações Técnicas da API

04. DEMAIS INFORMAÇÕES

05. ASSUNTOS RELACIONADOS