Histórico da Página

Versões
Visão Geral
Fluxo
Documentação

01. VERSÕES

Informações

icon	false

Informações

title	Integração dos Resultados

A partir dos patches:

12.1.2503.1
12.1.2411.

3

6
12.1.2407.12
ou superiores.

Informações

title	Integração dos Eventos e Sindicatos

A partir dos patches:

12.1.2503.4
12.1.2411.9
12.1.

2403

2407.15
ou superiores.

02. VISÃO GERAL

Proporcionar uma integração nativa entre o sistema Ahgora PontoWeb by TOTVS e o RH TOTVS Datasul. Essa integração permite a sincronização dos resultados apurados por meio do Integrator Ahgora. A execução ocorre manualmente, iniciada pelo usuário através da interface do Integrador 2.0 no PontoWeb, consolidando os dados filtrados na tela e enviando-os ao Datasul via API.

03. FLUXO

Deck of Cards

id	1

23

Card

default	true
id	1
label	Integração dos Resultados

Deck of Cards

id	Integração Resultados

Card

id

1-1
label	API - Envio Resultados Ponto
title	API - Envio Resultados Ponto

Objetivo: Realizar o envio, por parte da Ahgora, dos resultados apurados do ponto, permitindo a transferência de dados para vários funcionários simultaneamente.

Tipo de requisição: POST
Endpoint: api/rh/ahgora/v1

/ahgora

/results
Autenticação: Basic Authentication
- Para autenticação com o RH Datasul, basta ter um usuário com permissões da acesso as informações do funcionário, e utilizar o Basic Authentication usuário e senha.

- Sugestão que seja um usuário genérico, para evitar recadastro caso ocorra alteração de permissões de usuário.
Consumo de licenças Totvs I: Para utilização desta integração, é necessário a habilitação da licença I, que permite o acesso às APIs que disponibilizam estes dados. Caso você não possua a licença I, entre em contato com o seu ESN". Clique aqui para mais informações.

Body:

Nome	Descrição	Tipo	Obrigatório	Exemplo
items	Array de objetos funcionário	objeto	Sim

Objeto funcionário

Nome	Descrição	Tipo	Obrigatório	Exemplo
matricula	Matrícula do funcionário (campo exclusivo da Ahgora).	string	Sim	"10100000001"
anocomp	Ano competência.	string	Sim	"2024"
mescomp	Mês competência.	string	Sim	"12"
campoAdicional	Número do Pagamento	string	Sim	"01"
codfuncionario	Campo usado para identificar estabelecimento e matricula do funcionário. É composto por Empresa\|Estabelecimento\|Matricula.	string	Sim	"10\|1\|00000001"
resultados	Array de objetos rubrica, representa os resultados de ponto do funcionário.	objeto	Sim

Objeto evento

Nome	Descrição	Tipo	Obrigatório	Exemplo
rubrica	Composto

por Empresa + Evento. O sistema só irá considerar os últimos 4 dígitos para encontrar o código da evento.

pelo código do Evento.

string

Sim

"

10206

206"

referencia

Valor de referência, dado tipo da verba, será considerado como hora, valor.

Informações

Quando enviado como horas, deve ser considerado o formato centesimal.

Exemplo: o funcionário teve uma situação de jornada incompleta totalizando 1 hora e 30 min. Neste caso, deve ser enviado ao Datasul o valor de 1,50.

string

Sim

"1,

30

50"
datafalta	Será retornado a data da falta.	string	Não	"20240802"

Expandir

title	Exemplo Body

{
"items":[
{
"matricula":"

10100000001

1019445",
"anocom":"

2024

2023",
"mescom":"

12

11",
"campoAdicional":"",
"codfuncionario":"10|1|

0000001

9445",
"resultados":[
{
"rubrica":"

10206

103",
"referencia":"

1

15,

33

30",
"datafalta":"

20241202

"
}
]
}
]
}

Estrutura de Retorno:

O retorno é por rubrica processada, se foram enviados 6 funcionários, cada um com 2 rubricas. A api vai retornar 12 rubricas, cada uma com seu 'status' e 'mensagem'.

Nome	Descrição	Tipo	Obrigatório	Exemplo
response	Array de objetos resultado	objeto	Sim

Objeto resultado:

Nome	Descrição	Tipo	Obrigatório	Exemplo
resultados	Array de objetos rubrica, representa os resultados de ponto do funcionário.	objeto	Sim

Objeto rubrica:

Nome	Descrição	Tipo	Obrigatório	Exemplo
matricula	Matricula enviada na requisição	string	Sim	"1019445"
rubrica	Rubrica enviada na requisição.	string	Não	"103"
status	Informa se foi concluído ou não. Entende-se 'E' como erro e 'S' como sucesso.	string	Sim	"E" ou "S"
mensagem	Mensagem com descrição do status.	string	Sim	"Operação realizada com sucesso!"
referencia	Referencia enviada na requisição.	string	Não	"1,50"
datafalta	Data falta enviada na requisição.	string	Não	"20231101"

Expandir

title	Exemplo de retorno

{
"response":[
{

"

matricula

resultados":

"10100000002",

[

"anocom": "2024",

{
"

mescom

matricula":"

12

1019445",
"

codfuncionario

rubrica":"

10|1|0000002

103",
"

resultados

status":

[
{

"S",

"

rubrica

mensagem":"

10103

Operação realizada com sucesso!",

"referencia":"

2

15,30",

"datafalta":""

}

]

}
]

}

Informações

title	Importante

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

}

Card

id

cardidDe/ParaFP0780

1-2
label	De/Para
title	De/Para

Informações

title

3

label

De/Para

title

Movimento Parcelado

As informações integradas entre o PontoWeb e o RH Datasul são exibidas no programa FP2040 - Manutenção Movimento c/ Controle Parcela.
Com base nos dados enviados, são geradas as informações necessárias para o cálculo do funcionário, permitindo a criação de vencimentos ou descontos apurados pelo PontoWeb.

Tipo Informação	Regra

Cargos / Nível (Feedz - Cargos

Matricula (Empresa + Estab e Matricula)

FP0720

FP1500 - Manutenção

de Cargo

Unidade de Lotação (Feedz - Departamento)

do Funcionário
Ano / Mês Competencia	FP3000 - Manutenção de

Unidade

Habitação de

LotaçãoFuncionários (Feedz - Pessoas

Cálculo

Estabelecimentos (Feedz - Unidades)

FP0560 - Manutenção Estabelecimentos

codFuncionario (Empresa + |+ Estab + |+ Matricula)

FP1500 -

Funcionários / FP1510 - Funcionários Contratos Especiais

Pessoa Física (Feedz - Pessoas)

FP1440 - Manutenção Pessoa Física

Campo - Tipo de Desligamento (Feedz - dismissalType)

FP0060 - Manutenção Situação

Irá gravar o campo conforme regra abaixo:

- Quando o campo Iniciativa for igual a "Funcionário", grava 1
- Quando o campo Justa Causa, estiver desmarcado, grava 2
- Quando o campo Justa Causa, estiver marcado, grava 3

Card

id	4
label	Erros de Validação e seus Códigos

Lista de erros de validação e seus códigos

Alguns erros podem acontecer durante o processamento do lote enviado ou durante a validação dos itens do lote enviado, sendo eles:

Código

Mensagem

Detalhes

4998

Id do processo não encontrado

Significa que o processId informado na requisição de consulta de lotes está incorreto.

4999

Ocorreu um erro inesperado!

Representa erros genéricos ou inesperados que podem acontecer no servidor ou que podem ser gerados por algum aspecto incorreto não previsto do lote enviado.

5000

Token inválido ou expirado! / Bearer token não informado.

Isso indica que o token não foi informado na requisição ou informado não é válido. É necessário conferir se o token informado é igual à chave API na plataforma Feedz. Em caso afirmativo, é necessário gerar outra chave.

5000

Body vazio

Significa que foi enviada uma requisição para gravar um lote, mas sem nenhum dado.

5001

O total de itens enviados no corpo da requisição excede o limite de 100 registros. Todos os registros foram ignorados no processamento.

Ocorre ao enviar um lote com mais de 100 registros.

5003

A pessoa NPE (IntegrationId = IDN) está referenciando um gestor que não existe. Essa pessoa não será importada.

Esse erro ocorre ao tentar cadastrar um colaborador, vinculando a um gestor que ainda não foi cadastrado.

5004

A pessoa NPE (IntegrationId = IDN) está referenciando ela mesmo como chefe. Essa pessoa não será importada.

Esse erro ocorre ao tentar cadastrar um colaborador, vinculando ela mesma como gestora (integrationId = managerIntegrationId).

5005

A pessoa NPE (IntegrationId = IDN) está referenciando um departamento que não existe. Essa pessoa não será importada.

Esse erro ocorre ao tentar cadastrar um colaborador, vinculando a um departamento que ainda não foi cadastrado.

5006

A pessoa NPE (IntegrationId = IDN) está referenciando uma unidade que não existe. Essa pessoa não será importada.

Esse erro ocorre ao tentar cadastrar um colaborador, vinculando a uma unidade que ainda não foi cadastrada.

5008

A pessoa NPE (IntegrationId = IDN) está referenciando um cargo que não existe. Essa pessoa não será importada.

Esse erro ocorre ao tentar cadastrar um colaborador, vinculando a um cargo que ainda não foi cadastrado.

5009

O ID de integração (IntegrationId) é obrigatório e não foi informado para a Pessoa NPE. Essa pessoa não será importada.

Ocorre ao enviar uma pessoa e não informar se id de integração.

5011

O nome (Name) é obrigatório e não foi informado para a Pessoa (IntegrationId = IDN). Essa pessoa não será importada.

Ocorre ao enviar uma pessoa e não informar seu nome.

512

O e-mail (Email) é obrigatório e não foi informado para a Pessoa 'NPE' (IntegrationId = IDN). Essa pessoa não será importada.

Ocorre ao enviar uma pessoa e não informar seu e-mail.

5013

A pessoa 'NPE' (IntegrationId = IDN) possui o mesmo e-mail de outra pessoa da lista de pessoas enviadas ou da base. Essa pessoa não será importada.

Essa validação existe para evitar cadastrar pessoas duplicadas na base. Assim não é possível cadastrar dois e-mails iguais para integrationIds diferentes e vice versa.

5014

A pessoa 'NPE' (IntegrationId = IDN) deve ter o nome digitado somente com caracteres com nome, sobrenome e apenas 1(um) espaço entre eles.

Esse erro ocorre ao informar um nome inválido.

5015

A pessoa 'NPE' (IntegrationId = IDN) não pode ter o apelido igual ao nome.

Ocorre quando o name é igual ao socialName.

5016

O email fornecido 'EML' para a pessoa 'NPE' (IntegrationId = IDN) não está em um formato válido.

Ocorre ao enviar uma pessoa com o e-mail em formato inválido.

5017

O registro com o nome 'NRA' não foi salvo durante o processamento porque o campo 'IntegrationId' não foi informado."

Ocorre ao enviar qualquer registro auxiliar e não informar o integrationId.

5018

O registro com o código 'IDN' não foi salvo durante o processamento porque o campo 'Name' não foi informado.

Ocorre ao enviar qualquer registro auxiliar e não informar o nome.

5030

Quando informado a data de demissão deve ser também informado o motivo (dismissalType).

Ocorre ao enviar data de demissão e não informar o motivo.

5031

Deve ser informado o motivo da demissão (dismissalType) apenas quando for informado a data de demissão.

Ocorre ao enviar motivo da demissão e não informar a data de demissão.

5032

A data de admissão não pode ser maior que a data de demissão.

Ocorre ao enviar uma data de admissão posterior à data de demissão.

5048

O ID de integração do líder (managerIntegrationId = MII) informado para a pessoa (personIntegrationId = IDN) não existe.

Ocorre ao tentar vincular pessoa e líder pela rota persons-bind e não ter esse líder cadastrado previamente na plataforma.

5049

O ID de integração da pessoa (personIntegrationId = IDN) informada não existe.

Ocorre ao tentar vincular pessoa e líder pela rota persons-bind e não ter esse colaborador cadastrado previamente na plataforma.

5050

Uma pessoa (personIntegrationId = IDN) não pode ser líder de sí próprio

Ocorre ao tentar vincular uma pessoa a ela mesma como líder (personIntegrationId = managerIntegrationId) através da rota persons-bind.

Manutenção do Funcionário
Rubrica	FP0020 - Manutenção Eventos

Card

id	1-3
label	Erros Validação

Lista de erros que podem ocorrer durante a integração.

Mensagem	Detalhes
Folha Normal já calculada.	Isso significa que a Folha de Pagamento já foi iniciada para o funcionário. Para corrigir, é necessário eliminar o cálculo do funcionário em questão e realizar novamente a integração entre o Integrador do PontoWeb e o RH Datasul.
Quantidade deve ser maior ou igual a 0 (zero).	Isso significa que o valor ou horas, são menores que zero.
Evento inexistente.	Isso significa que o evento não foi encontrado na base do RH Datasul.
Funcionário inexistente.	Isso significa que o funcionário não foi encontrado na base do RH Datasul.
Ano/Mês competência incorreto(s).	Isso significa que a Folha de Pagamento já esta concluída para o funcionário. Período dos envios é anterior à habilitação do cálculo. Nesse caso, é importante verificar se a competência informada está correta.
Já existe ocorrência Situação Afastamento informada.	Isso significa que já exista uma situação de afastamento informado para a mesma da datafalta.
Evento não está relacionado a uma falta injustificada.	Isso significa que o evento não está informado no FP0060. Quando a datafalta é informada no envio dos resultados, o programa verifica as situações de afastamento do tipo 'falta injustificada' que contenham o evento informado na aba Ponto, nos campos 'Afastamento Diurno' e 'Afastamento Noturno', tanto para horistas quanto para mensalistas.
Campo codfuncionario Inválido	Isso significa que o campo Matrícula contém informações inválidas, pois não segue o formato recomendado e não está devidamente separado por pipe. Ex.: Emp\|Estab\|Func
Matricula do Funcionário Inválido	Isso significa que o campo Matrícula está em branco, ou seja, não foi informado no envio.

Card

id	2
label	Integração dos Eventos

Deck of Cards

id	Integração dos Eventos

Card

id	2-1
label	Integração dos Eventos
title	API - Envio Resultados Ponto

Objetivo: Realizar a importação dos eventos cadastrado no Datasul com base no CNPJ cadastrados no Ahgora.

Para a integração dos eventos, é necessário que o estabelecimento já esteja cadastrado no Ahgora. Com os dados do estabelecimento cadastrados, a solicitação de envio dos eventos utilizará o CNPJ.
Importante: nesse contexto, para localizar a empresa, utilizamos apenas os 8 primeiros dígitos do CNPJ informado.
Com base nesse CNPJ, o sistema retornará todos os eventos vinculados à empresa. Caso a base esteja configurada com o campo "Utiliza Eventos por Empresa", os eventos retornados serão os cadastrados no nível da empresa.

Tipo de requisição: POST
Endpoint: api/rh/ahgora/v1/verbas
Autenticação: Basic Authentication
- Para autenticação com o RH Datasul, basta ter um usuário com permissões da acesso as informações do funcionário, e utilizar o Basic Authentication usuário e senha.
- Sugestão que seja um usuário genérico, para evitar recadastro caso ocorra alteração de permissões de usuário.
Consumo de licenças Totvs I: Para utilização desta integração, é necessário a habilitação da licença I, que permite o acesso às APIs que disponibilizam estes dados. Caso você não possua a licença I, entre em contato com o seu ESN". Clique aqui para mais informações.

Objeto da Solicitação

- É enviado a pagina 1 até 500, com a lista de CNPJ para retorno dos eventos. Conforme exemplo abaixo.
  - ...endpoint...verbas?page=1&pageSize=500&cnpjList=11111111000111,11111111000222

Objeto Retorno

Campo	Descrição	Tipo	Obrigatório
Código	Código do evento	string	Sim
Descrição	Descrição do evento	string	Sim
CNPJ	CNPJ do Estabelecimento	string	Sim
Categoria	São as informações concatenadas dos do evento Identificação + Unidade Os valores possível na identificação: Vencimento Desconto Outros Os valores possíveis na Unidade Hora Valor Dia Padrão Dia Real Avos Quantidade	string	Sim

Expandir

title	Exemplo Body

{
"response": [
{
"items": [
{
"categoria": "Vencimento - Hora",
"cod": "001",
"cnpj": "11.111.111/0001-11",
"desc": "Hrs Normais Diurnas"
},
{
"categoria": "Vencimento - Hora",
"cod": "001",
"cnpj": "11.111.111/0002-22",
"desc": "Hrs Normais Diurnas"
}
]
}
],
"hasNext": true
}

Card

id	2-2
label	De/Para
title	De/Para

Lista dos campos e ondem podemos encontrar no Datasul.

Tipo Informação	Regra
Código Evento / Descrição / Identificação e Unidade	FP0020 - Manutenção Eventos Analíticos Geral
CNPJ	FP0560 - Manutenção Informações Gerais Estabelecimentos

Card

id	2-3
label	Erros Validação

Lista de erros que podem ocorrer durante a integração.

Mensagem	Detalhes
CNPJ Invalido	Isso significa que o CNPJ informado no Ahgora não foi encontrado nos cadastrados do Datasul. FP0500 - Manutenção Parâmetros por Empresa HCM FP0560 - Manutenção Informações Gerais Estabelecimentos

Card

id	3
label	Integração dos Sindicatos

Deck of Cards

id	Integração dos Sindicatos

Card

id	3-1
label	Integração dos Sindicatos
title	Integração dos Sindicatos

Objetivo: Realizar a importação dos sindicatos cadastrados no Datasul com base no CNPJ cadastrados no Ahgora.

Para a integração dos sindicatos, é necessário que o estabelecimento já esteja cadastrado no Ahgora. Com os dados do estabelecimento cadastrados, a solicitação de envio dos sindicatos utilizará o CNPJ.
Importante: nesse contexto, para localizar a empresa, utilizamos apenas os 8 primeiros dígitos do CNPJ informado.
Com base nesse CNPJ, o sistema retornará todos os sindicatos vinculados à empresa e ao estabelecimento. A API utiliza o cadastro FP0570 - Manutenção Informações Complementares do Estabelecimento para buscar as informações relacionadas ao estabelecimento e ao sindicato.

Tipo de requisição: POST
Endpoint: api/rh/ahgora/v1/sindicatos
Autenticação: Basic Authentication
- Para autenticação com o RH Datasul, basta ter um usuário com permissões da acesso as informações do funcionário, e utilizar o Basic Authentication usuário e senha.
- Sugestão que seja um usuário genérico, para evitar recadastro caso ocorra alteração de permissões de usuário.
Consumo de licenças Totvs I: Para utilização desta integração, é necessário a habilitação da licença I, que permite o acesso às APIs que disponibilizam estes dados. Caso você não possua a licença I, entre em contato com o seu ESN". Clique aqui para mais informações.

Objeto da Solicitação

- É enviado a pagina 1 até 500, com a lista de CNPJ para retorno dos sindicatos. Conforme exemplo abaixo.
  - ...endpoint...sindicatos?page=1&pageSize=500&cnpjList=11111111000111,11111111000222

Objeto Retorno

Campo	Descrição	Tipo	Obrigatório
Código	Código do sindicato	string	Sim
Descrição	Descrição do sindicato	string	Sim
CNPJ	CNPJ do Estabelecimento	string	Sim

Expandir

title	Exemplo Body

{
"response": [
{
"items": [
{
"cod": "1",
"cnpj": "11.111.111/0001-11",
"desc": "SIND.TR.Teste"
},
{
"cod": "1",
"cnpj": "11.111.111/0002-22",
"desc": "SIND.TR.Teste II"
}
]
}
],
"hasNext": true
}

Card

id	3-2
label	De/Para
title	De/Para

Lista dos campos e ondem podemos encontrar no Datasul.

Tipo Informação	Regra
Código Sindicato e Descrição	FP0600 - Manutenção Sindicatos
CNPJ	FP0560 - Manutenção Informações Gerais Estabelecimentos

Card

id	3-3
label	Erros Validação

Lista de erros que podem ocorrer durante a integração.

Mensagem	Detalhes
CNPJ Invalido	Isso significa que o CNPJ informado no Ahgora não foi encontrado nos cadastrados do Datasul. FP0500 - Manutenção Parâmetros por Empresa HCM FP0560 - Manutenção Informações Gerais Estabelecimentos

Árvore de páginas

Versões comparadas

Versão antiga 8

Nova versão Atual

Chave

01. VERSÕES

02. VISÃO GERAL

03. FLUXO

Lista de erros de validação e seus códigos

Lista de erros que podem ocorrer durante a integração.

04. DOCUMENTAÇÃO