Linha Datasul

Árvore de páginas

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

01. VERSÕES

Integração dos Resultados

A partir dos patches:

  • 12.1.2503.1
  • 12.1.2411.6
  • 12.1.2407.12
  • ou superiores.

Integração dos Eventos e Sindicatos

A partir dos patches:

  • 12.1.2503.4
  • 12.1.2411.9
  • 12.1.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

 

      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/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 pelo código do Evento.

      		 string

      Sim

      "206"

      referencia

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

      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,50"

      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": "103",
                          "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, 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"

      {
          "response": [
            {
              "resultados": [
                {
                  "matricula": "1019445",
                  "rubrica": "103",
                  "status": "S",
                  "mensagem": "Operação realizada com sucesso!",
                  "referencia": "15,30",
                  "datafalta": ""
                }
              ]
            }
          ]
        }

      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
      Matricula (Empresa + Estab e Matricula)

      FP1500 - Manutenção do Funcionário
      Ano / Mês Competencia FP3000 - Manutenção de Habitação de Cálculo
      codFuncionario (Empresa + |+ Estab + |+ Matricula) FP1500 - Manutenção do Funcionário
      Rubrica

      FP0020 - Manutenção Eventos

      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.

        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

        {
            "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
        }

        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

        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

          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

          {
              "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
          }

          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

          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

           

          04.  DOCUMENTAÇÃO