1. Versões
  2. Visão Geral
  3. Fluxo

01. VERSÕES

A partir dos patches:

  • 12.1.2411.3
  • 12.1.2407.9
  • 12.1.2403.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

 

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/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. 


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.

string

Sim

"10206"

referencia

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

string

Sim

"1,30"

datafalta

Será retornado a data da falta.

string

Não

"20240802"

{
    "items": [
        {
            "matricula": "1019445",
            "anocom": "2023",
            "mescom": "11",
            "campoAdicional": "",
            "codfuncionario": "10|1|9445",
            "resultados": [                
                {
                    "rubrica": "10103",
                    "referencia": "15,30",
                    "datafalta": ""
                }
            ]
        }
    ]
}


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

objeto

Sim



Objeto rubrica:

Nome

Descrição

Tipo

Obrigatório

Exemplo

matricula

Matricula enviada na requisição

string

Sim

"0101000001"

rubrica

Rubrica enviada na requisição.

string

Não

"10001"

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

"Verba inválida."

referencia

Referencia enviada na requisição.

string

Não

"1,59"

datafalta

Data falta enviada na requisição.

string

Não

"20240802"

Exemplo de retorno, sucesso.

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

Tipo InformaçãoRegra
Cargos / Nível (Feedz - Cargos)

FP0720 - Manutenção de Cargo

Unidade de Lotação (Feedz - Departamento)FP0780 - Manutenção de Unidade de Lotação
Estabelecimentos (Feedz - Unidades)FP0560 - Manutenção Estabelecimentos
Funcionários (Feedz - Pessoas)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

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.