Contexto de negócio

Cada vez mais o mercado exige que as operações complexas e manipulação de dados sejam ainda mais ágeis e com custos reduzidos. Com o RH não é diferente, os processos cada vez mais complexos e com muitas variáveis a serem analisadas no que tange a segurança e medicina do trabalho, os profissionais de saúde precisam de agilidade na hora de controlar processos funcionais da empresa.

Com essa necessidade e a importância desta área dentro da empresa, softwares especialistas em medicina e segurança do trabalho estão cada vez mais presentes no mercado e foi neste contexto que surgiu a necessidade da criação de um produto que possibilite automatizar cadastros e rotinas de funcionais dentro do ERP através de uma interface de integração.

QUÍRONS

Software desenvolvido pela NG, empresa com ampla experiência em gestão de medicina e segurança do trabalho, sendo pioneira na administração de processos funcionais e com atuação no mercado a mais de trinta anos tendo vários cases de sucesso.(Dados extraídos do site do próprio parceiro, mais informações).

Pré requisitos, instalação, configuração e configuração REST

(Acesse a documentação aqui)

Integrações Disponíveis


    Relação de Tipos de Abono - allowanceTypes - INTEGRAÇÃO PONA050API

    Sistemas Envolvidos

    Descrição dos sistemas envolvidos no contexto de negócio (e que serão envolvidos na integração).

    • Protheus (módulo de Ponto Eletrônico): Módulo responsável pela gestão da assiduidade e marcações/apontamentos de horários de trabalho do funcionário, dentre outros cadastros pertinentes aos colaboradores.
    • Quírons - NG

    Integração

    O objetivo desta integração é permitir que a área do RH ou área responsável pelas marcações/apontamentos de horário, envie os dados do cadastro de tipos de abono para o sistema da NG e assim reduzir o trabalho de inclusão manual de todas as informações dentro do sistema.

    • Benefícios 
      • Normalmente o colaborador responsável inclui as informações de cadastros de tipos de abono através de um arquivo (csv, txt) ou até mesmo manualmente. Com a interface de integração isso será feito de forma  automática.
      • Não terá um investimento alto de tempo para o cadastramento, pois os dados já serão enviados através da integração a cada requisição do sistema especialista.
    • Arquitetura (Tecnologia)
      • Toda integração entre o Protheus e o Quírons é feita por intermédio de comunicação direta com os Web Services (que são fixos)  REST(Representation State Transfer) utilizando o formato JSON (JavaScript  Object Notation) de serialização de dados, onde através da ativação do serviço do REST do Protheus esteja disponível para utilizar o serviço.
    • Premissas e Propriedades
      • O parceiro que será responsável pela requisição e transformação da informação recebida;
      • Cada produto deverá gerar um LOG de inclusão(P6_USERLGI) ou alteração (P6_USERLGA) de registros a fim de controlar os dados a serem integrados;
      • Na requisição, o parceiro deverá informar  através do preenchimento do parâmetro datemodified se desejar uma carga completa(deixar o parâmetro vazio) ou somente os dados que foram atualizados(Informando a data de alteração). Caso seja solicitada a carga, todos os dados serão enviados novamente. Caso seja  solicitado uma atualização, somente os dados com data igual ou posterior a data informada, serão transmitidos;
      • Será implementado um controle de paginação a fim de facilitar o envio da informação para o solicitante. Neste processo o solicitante deverá informar qual é o tamanho da informação solicitada e qual página ele solicita;
      • Cabe a integração informar se existem mais páginas a serem solicitadas;

    Ativação/Desativação da integração

    Por padrão esta integração estará em repositório, porém demanda realizar a devida configuração conforme abaixo:

    Controle de Ambiente

    Exige que os seguintes pontos sejam revisados:

    • Protheus com sua arquitetura devidamente estruturada.
    • Módulo Ponto Eletrônico com os dados do cadastro de Tipo de abono devidamente inseridos.

    Controle de Versão

    O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

    Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das marcas e alinhamento com as diretivas definidas pelo Comitê de Integração TOTVS.

    Suporte

    O suporte aos recursos da Integração será de responsabilidade da linha Protheus, onde será analisada pela equipe de suporte da Totvs.

    Fluxo das Informações

    Esta integração traz a funcionalidade exclusivamente para exportação do cadastro de Tipos de Abono.

    Cadastro

    Esta integração contempla apenas a consulta e envio dos dados de Tipos de Abono.

    Processos

    A solicitante realizará o consumo da API com dados básicos que serão utilizados como parâmetros para consultar a base  e retornar um conjunto de informações pertinentes ao cadastro de Tipos de Abono.

    Limitações / Restrições Gerais

    • A integração não contemplará inclusão,alteração e exclusão de registros no Protheus, para isso o usuário deverá acessar o ERP e efetuar as devidas ações manualmente.
    • Cada produto deverá gerar um LOG de inclusão e alteração de registros a fim de controlar os dados a serem integrados;
    • A data de alteração do registro deverá ser enviada em cada processo, permitindo que o solicitante possa controlar essa informação;


    Como realizar a chamada da API REST

    Para realizar a integração com o parceiro TOTVS é necessário as informações básicas de consulta para retorno dos tipos de abono desejados.

    • Preenchimento do EndPoint da API PONA050API;
    • Utilizar a chamada do método Get e do Serviço allowanceTypes;
    • Preenchimento dos parâmetros obrigatórios da API;

    Formatos de Data

    As Entradas e Saídas de dados tipo data(Date) acompanham o formato padrão YYYY-MM-DDThh:mm

    Parâmetros de Entrada:

    Parâmetro

    Valor de Exemplo

    Obrigatório

    Tipo Parâmetro

    Valor Default

    Descrição
    page 1 Não

    Integer

    query 1 Página que está sendo requisitada.
    pageSize 1 Não

    Integer

    query

    2000

    Quantidade de tipos de abono por página.
    datemodified 2001-01-01T18:25:43 Não String query
    Data que será utilizada como filtro para trazer tipos de abono com data de alteração (P6_USERLGA) ou inclusão (P6_USERLGI).
    branchId D MG 01 Sim String query

    companyId T1 Sim String query

    authorization

    não será informado pelos parâmetros REST Sim String header
    Configuração do parâmetro 

    Security = 1 no arquivo appserver.ini


    Parâmetros e Chamada do Método:

    Para a realização de testes foi utilizado a ferramenta SOAP UI e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

    {protocolo}://{host}/{api}/rh/v2/allowanceTypes/

    Response da API:


    Response allowanceTypes
    {
        "items": [
            {
                "branchId": "D MG    ",
                "code": "009",
                "companyId": "T1",
                "name": "ABONO INTEGRAL",
                "id": "T1|D MG    |009|"
            },
            {
                "branchId": "D MG    ",
                "code": "107",
                "companyId": "T1",
                "name": "ABONO ATRASO",
                "id": "T1|D MG    |107|"
            },
            {
                "branchId": "D MG    ",
                "code": "114",
                "companyId": "T1",
                "name": "ABONO FALTAS",
                "id": "T1|D MG    |114|"
            },
            {
                "branchId": "D MG    ",
                "code": "115",
                "companyId": "T1",
                "name": "ABONO 1/2 FALTA",
                "id": "T1|D MG    |115|"
            }
        ],
        "hasNext": false
    }
    

    Situações de Erros Tratados

    O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros. Desta forma, foram criados alguns tratamentos de erros listados abaixo, cada um com sua respectiva mensagem e solução.

    Tratamento de erros de integração Protheus:

    Mensagens de Pré-Validação

    Erro

    Mensagem

    Solução

    400

    Campo P6_USERLGI / P6_USERLGA não foi encontrado.

    Campos _USERLGA/_USERLGI
    {
        "code": 400,
        "detailedMessage": "Campo USERLGA não foi encontrado: Entidade (SP6)",
        "helpUrl": "https://tdn.totvs.com/x/BJuMHw",
        "message": "Campo USERLGA não foi encontrado: Entidade (SP6)"
    }
    400

    A Filial é um parâmetro obrigatório.

    Quando o campo branchId está em branco.
    {
       "code": 400,
       "detailedMessage": "Falha ao validar as informações básicas da assinatura. Informação: branchId",
       "helpUrl": "https://tdn.totvs.com/x/BJuMHw",
       "message": "Falha ao validar as informações básicas da assinatura. Informação: branchId"
    }
    400 O Grupo de Empresa é um parâmetro obrigatório 
    Erro quando campo companyId está vazio.
    {
       "code": 400,
       "detailedMessage": "Falha ao validar as informações básicas da assinatura. Informação: companyId",
       "helpUrl": "https://tdn.totvs.com/x/BJuMHw",
       "message": "Falha ao validar as informações básicas da assinatura. Informação: companyId"
    }


    Checklist de suporte da aplicação

    Itens a serem verificados durante o atendimento:

    • Verificar se os pré-requisitos foram atendidos para a chamada da API;
    • Verificar se na chamada da API o EndPoint, o nome do serviço e todos os campos obrigatórios foram informados;
    • Verificar se o retorno da API apresenta algum erro tratado (códigos e mensagens de erro citados neste documento) e consultar a solução na mesma tabela que descreve o erro;
    • Em caso de Erro não tratado, verificar se possui alguma informação de banco de dados, conexão com o servidor ou algo que possa identificar a origem do problema.


    Relação de Centros de Custos - payrollCostCenter - INTEGRAÇÃO GPEA002API 

    Sistemas Envolvidos

    Descrição dos sistemas envolvidos no contexto de negócio (e que serão envolvidos na integração).

    • Protheus (módulo de Gestão de Pessoal): Módulo responsável pela gestão do funcionário.
    • Quírons - NG

    Integração

    O objetivo desta integração é permitir que a área do RH ou área responsável pelo controle de centros de custos, envie os dados do cadastro de centro de custo para o sistema da NG e assim reduzir o trabalho de inclusão manual de todas as informações dentro do sistema.

    • Benefícios 
      • Normalmente o colaborador responsável inclui as informações de cadastros de centro de custo através de um arquivo (csv, txt) ou até mesmo manualmente. Com a interface de integração isso será feito de forma  automática.
      • Não terá um investimento alto de tempo para o cadastramento, pois os dados já serão enviados através da integração a cada requisição do sistema especialista.
    • Arquitetura (Tecnologia)
      • Toda integração entre o Protheus e o Quírons é feita por intermédio de comunicação direta com os Web Services (que são fixos)  REST(Representation State Transfer) utilizando o formato JSON (JavaScript  Object Notation) de serialização de dados, onde através da ativação do serviço do REST do Protheus esteja disponível para utilizar o serviço.
    • Premissas e Propriedades
      • O parceiro que será responsável pela requisição e transformação da informação recebida;
      • Cada produto deverá gerar um LOG de inclusão(CTT_USERGI) ou alteração (CTT_USERGA) de registros a fim de controlar os dados a serem integrados;
      • Na requisição, o parceiro deverá informar  através do preenchimento do parâmetro datemodified se desejar uma carga completa(deixar o parâmetro vazio) ou somente os dados que foram atualizados(Informando a data de alteração). Caso seja solicitada a carga, todos os dados serão enviados novamente. Caso seja  solicitado uma atualização, somente os dados com data igual ou posterior a data informada, serão transmitidos;
      • Será implementado um controle de paginação a fim de facilitar o envio da informação para o solicitante. Neste processo o solicitante deverá informar qual é o tamanho da informação solicitada e qual página ele solicita;
      • Cabe a integração informar se existem mais páginas a serem solicitadas;

    Ativação/Desativação da integração

    Por padrão esta integração estará em repositório, porém demanda realizar a devida configuração conforme abaixo:

    Controle de Ambiente

    Exige que os seguintes pontos sejam revisados:

    • Protheus com sua arquitetura devidamente estruturada.
    • Módulo Gestão de Pessoal com os dados de Centro de Custo devidamente inseridos.

    Controle de Versão

    O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

    Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das marcas e alinhamento com as diretivas definidas pelo Comitê de Integração TOTVS.

    Suporte

    O suporte aos recursos da Integração será de responsabilidade da linha Protheus, onde será analisada pela equipe de suporte da Totvs.

    Fluxo das Informações

    Esta integração traz a funcionalidade exclusivamente para exportação do cadastro de centro de custo.

    Cadastro

    Esta integração contempla apenas a consulta e envio dos dados de cadastro de centro de custo.

    Processos

    A solicitante realizará o consumo da API com dados básicos que serão utilizados como parâmetros para consultar a base  e retornar um conjunto de informações pertinentes ao cadastro de centro de custo.

    Limitações / Restrições Gerais

    • A integração não contemplará inclusão,alteração e exclusão de registros no Protheus, para isso o usuário deverá acessar o ERP e efetuar as devidas ações manualmente.
    • Cada produto deverá gerar um LOG de inclusão e alteração de registros a fim de controlar os dados a serem integrados;
    • A data de alteração do registro deverá ser enviada em cada processo, permitindo que o solicitante possa controlar essa informação;


    Como realizar a chamada da API RESTMatrícula não existe no Protheus(SRA).

    Para realizar a integração com o parceiro TOTVS é necessário as informações básicas de consulta para retorno dos centros de custos desejados.

    • Preenchimento do EndPoint da API GPEA002API;
    • Utilizar a chamada do método Get e do Serviço payrollcostcenter;
    • Preenchimento dos parâmetros obrigatórios da API;

    Formatos de Data

    As Entradas e Saídas de dados tipo data(Date) acompanham o formato padrão YYYY-MM-DDThh:mm

    Parâmetros de Entrada:

    Parâmetro

    Valor de Exemplo

    Obrigatório

    Tipo Parâmetro

    Valor Default

    Descrição
    page 1 Não

    Integer

    query
    Página que está sendo requisitada.
    pageSize 1 Não

    Integer

    query

    2000

    Quantidade de centros de custo por página.
    datemodified 2001-01-01T18:25:43 Não String query
    Data que será utilizada como filtro para trazer funcionários com data de alteração (CTT_USERGA) ou inclusão (CTT_USERGI).
    branchId D MG 01 Sim String query

    companyId T1 Sim String query

    authorization

    não será informado pelos parâmetros REST Sim String header
    Configuração do parâmetro 

    Security = 1 no arquivo appserver.ini


    Parâmetros e Chamada do Método:

    Para a realização de testes foi utilizado a ferramenta SOAP UI e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

    {protocolo}://{host}/{api}//rh/v1/payrollcostcenter/

    Response da API:


    Response PayrollCostCenter

    {
        "items": [
            {
                "code": "000000009",
                "companyId": "T1",
                "name": "DEPARTAMENTO DE PESSOAL",
                "id": "T1|D MG 01 |000000009",
                "branch": "D MG 01 "
            },
            {
                "code": "000000013",
                "companyId": "T1",
                "name": "MEURH",
                "id": "T1|D MG 01 |000000013",
                "branch": "D MG 01 "
            }
        ],
        "hasNext": false
    }

    Situações de Erros Tratados

    O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros. Desta forma, foram criados alguns tratamentos de erros listados abaixo, cada um com sua respectiva mensagem e solução.

    Tratamento de erros de integração Protheus:

    Mensagens de Pré-Validação

    Erro

    Mensagem

    Solução

    400

    Campo CTT_USERGA / CTT_USERGA não foi encontrado.

    Quando o campo branchId está em branco.

    {
        "code": 400,
        "detailedMessage""Campo USERLGA não foi encontrado: Entidade (CTT)",
        "helpUrl""https://tdn.totvs.com/x/BJuMHw",
        "message""Campo USERGA não foi encontrado: Entidade (CTT)"
    }

    400

    A Filial é um parâmetro obrigatório.

    Quando o campo branchId está em branco.

    {
       "code": 400,
       "detailedMessage": "Falha ao validar as informações básicas da assinatura. Informação: branchId",
       "helpUrl": https://tdn.totvs.com/x/BJuMHw,
       "message": "Falha ao validar as informações básicas da assinatura. Informação: branchId"
    }

    400 O Grupo de Empresa é um parâmetro obrigatório 

    Erro quando campo companyId está vazio.

    {
       "code": 400,
       "detailedMessage": "Falha ao validar as informações básicas da assinatura. Informação: companyId",
       "helpUrl": "https://tdn.totvs.com/x/BJuMHw",
       "message": "Falha ao validar as informações básicas da assinatura. Informação: companyId"
    }

    Checklist de suporte da aplicação

    Itens a serem verificados durante o atendimento:

    • Verificar se os pré-requisitos foram atendidos para a chamada da API;
    • Verificar se na chamada da API o EndPoint, o nome do serviço e todos os campos obrigatórios foram informados;
    • Verificar se o retorno da API apresenta algum erro tratado (códigos e mensagens de erro citados neste documento) e consultar a solução na mesma tabela que descreve o erro;
    • Em caso de Erro não tratado, verificar se possui alguma informação de banco de dados, conexão com o servidor ou algo que possa identificar a origem do problema.



    Relação de Turnos de Trabalho workingShift - INTEGRAÇÃO PONA080API 

    Sistemas Envolvidos

    Descrição dos sistemas envolvidos no contexto de negócio (e que serão envolvidos na integração).

    • Protheus (módulo  Ponto Eletrônico) Módulo responsável pela gestão da assiduidade e marcações/apontamentos de horários de trabalho do funcionário, dentre outros cadastros pertinentes aos colaboradores.
    • Quírons - NG

    Integração

    O objetivo desta integração é permitir que a área do RH ou área responsável pelas marcações/apontamentos de horário, envie os dados do cadastro de turnos de trabalho para o sistema da NG e assim reduzir o trabalho de inclusão manual de todas as informações dentro do sistema.

    • Benefícios 
      • Normalmente o colaborador responsável inclui as informações de cadastros de turnos de trabalho através de um arquivo (csv, txt) ou até mesmo manualmente. Com a interface de integração isso será feito de forma  automática.
      • Não terá um investimento alto de tempo para o cadastramento, pois os dados já serão enviados através da integração a cada requisição do sistema especialista.
    • Arquitetura (Tecnologia)
      • Toda integração entre o Protheus e o Quírons é feita por intermédio de comunicação direta com os Web Services (que são fixos)  REST(Representation State Transfer) utilizando o formato JSON (JavaScript  Object Notation) de serialização de dados, onde através da ativação do serviço do REST do Protheus esteja disponível para utilizar o serviço.
    • Premissas e Propriedades
      • O parceiro que será responsável pela requisição e transformação da informação recebida;
      • Cada produto deverá gerar um LOG de inclusão(R6_USERLGI) ou alteração (R6_USERLGA) de registros a fim de controlar os dados a serem integrados;
      • Na requisição, o parceiro deverá informar  através do preenchimento do parâmetro datemodified se desejar uma carga completa(deixar o parâmetro vazio) ou somente os dados que foram atualizados(Informando a data de alteração). Caso seja solicitada a carga, todos os dados serão enviados novamente. Caso seja  solicitado uma atualização, somente os dados com data igual ou posterior a data informada, serão transmitidos;
      • Será implementado um controle de paginação a fim de facilitar o envio da informação para o solicitante. Neste processo o solicitante deverá informar qual é o tamanho da informação solicitada e qual página ele solicita;
      • Cabe a integração informar se existem mais páginas a serem solicitadas;

    Ativação/Desativação da integração

    Por padrão esta integração estará em repositório, porém demanda realizar a devida configuração conforme abaixo:

    Controle de Ambiente

    Exige que os seguintes pontos sejam revisados:

    • Protheus com sua arquitetura devidamente estruturada.
    • Módulo Ponto Eletrônico com os dados do cadastro de Tipo de abono devidamente inseridos.

    O objetivo desta integração é permitir que a área do RH ou área responsável pelos benefícios, envie os dados do cadastro de turnos para o sistema da NG e assim reduzir o trabalho de inclusão manual de todas as informações dentro do sistema.

    Controle de Versão

    O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

    Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das marcas e alinhamento com as diretivas definidas pelo Comitê de Integração TOTVS.

    Suporte

    O suporte aos recursos da Integração será de responsabilidade da linha Protheus, onde será analisada pela equipe de suporte da Totvs.

    Fluxo das Informações

    Esta integração traz a funcionalidade exclusivamente para exportação do cadastro de Turnos de Trabalho.

    Cadastro

    Esta integração contempla apenas a consulta e envio dos dados de Turnos de Trabalho.

    Processos

    A solicitante realizará o consumo da API com dados básicos que serão utilizados como parâmetros para consultar a base  e retornar um conjunto de informações pertinentes ao cadastro de Turnos de Trabalho.

    Limitações / Restrições Gerais

    • A integração não contemplará inclusão,alteração e exclusão de registros no Protheus, para isso o usuário deverá acessar o ERP e efetuar as devidas ações manualmente.
    • Cada produto deverá gerar um LOG de inclusão e alteração de registros a fim de controlar os dados a serem integrados;
    • A data de alteração do registro deverá ser enviada em cada processo, permitindo que o solicitante possa controlar essa informação;

    Como realizar a chamada da API REST

    Para realizar a integração com o parceiro TOTVS é necessário as informações básicas de consulta para retorno dos tipos de abono desejados.

    • Preenchimento do EndPoint da API PONA080API;
    • Utilizar a chamada do método Get e do Serviço workingShift;
    • Preenchimento dos parâmetros obrigatórios da API;

    Formatos de Data

    As Entradas e Saídas de dados tipo data(Date) acompanham o formato padrão YYYY-MM-DDThh:mm

    Parâmetros de Entrada:

    Parâmetro

    Valor de Exemplo

    Obrigatório

    Tipo Parâmetro

    Valor Default

    Descrição
    page 1 Não

    Integer

    query 1 Página que está sendo requisitada.
    pageSize 1 Não

    Integer

    query

    2000

    Quantidade de turnos por página.
    datemodified 2001-01-01T18:25:43 Não String query
    Data que será utilizada como filtro para trazer turnos com data de alteração (R6_USERLGA) ou inclusão (R6_USERLGI).
    branchId D MG 01 Sim String query

    companyId T1 Sim String query

    authorization

    não será informado pelos parâmetros REST Sim String header
    Configuração do parâmetro 

    Security = 1 no arquivo appserver.ini


    Parâmetros e Chamada do Método:

    Para a realização de testes foi utilizado a ferramenta SOAP UI e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

    {protocolo}://{host}/{api}//rh/v1/workingShift/

    Response da API:


    Response WorkingShift

    {
        "items": [
            {
                "branchId": "D MG    ",
                "companyId": "T1",
                "workingShiftCode": "001",
                "name": "TURNO PADRAO",
                "monthlyWorkLoad": "",
                "id": "T1|D MG    |001|"
            },
            {
                "branchId": "D MG    ",
                "companyId": "T1",
                "workingShiftCode": "005",
                "name": "DRHPAG-28863",
                "monthlyWorkLoad": "",
                "id": "T1|D MG    |005|"
            },  
       
            {
                "branchId": "D MG    ",
                "companyId": "T1",
                "workingShiftCode": "010",
                "name": "DRHPAG-31556",
                "monthlyWorkLoad": "",
                "id": "T1|D MG    |010|"
            }
        ],
        "hasNext": false
    }

    Situações de Erros Tratados

    O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros. Desta forma, foram criados alguns tratamentos de erros listados abaixo, cada um com sua respectiva mensagem e solução.

    Tratamento de erros de integração Protheus:

    Mensagens de Pré-Validação

    Erro

    Mensagem

    Solução

    400

    Campo R6_USERLGI / R6_USERLGA não foi encontrado.

    Campos _USERLGA/_USERLGI

    {
        "code": 400,
        "detailedMessage": "Campo USERLGA não foi encontrado: Entidade (SR6)",
        "helpUrl": "https://tdn.totvs.com/x/BJuMHw",
        "message": "Campo USERLGA não foi encontrado: Entidade (SR6)"
    }

    400

    A Filial é um parâmetro obrigatório.

    Quando o campo branchId está em branco.

    {
       "code": 400,
       "detailedMessage": "Falha ao validar as informações básicas da assinatura. Informação: branchId",
       "helpUrl": "https://tdn.totvs.com/x/BJuMHw",
       "message": "Falha ao validar as informações básicas da assinatura. Informação: branchId"
    }

    400 O Grupo de Empresa é um parâmetro obrigatório 

    Erro quando campo companyId está vazio.

    {
       "code": 400,
       "detailedMessage": "Falha ao validar as informações básicas da assinatura. Informação: companyId",
       "helpUrl": "https://tdn.totvs.com/x/BJuMHw",
       "message": "Falha ao validar as informações básicas da assinatura. Informação: companyId"
    }

    Checklist de suporte da aplicação

    Itens a serem verificados durante o atendimento:

    • Verificar se os pré-requisitos foram atendidos para a chamada da API;
    • Verificar se na chamada da API o EndPoint, o nome do serviço e todos os campos obrigatórios foram informados;
    • Verificar se o retorno da API apresenta algum erro tratado (códigos e mensagens de erro citados neste documento) e consultar a solução na mesma tabela que descreve o erro;
    • Em caso de Erro não tratado, verificar se possui alguma informação de banco de dados, conexão com o servidor ou algo que possa identificar a origem do problema.



    Relação de Funções - positions  - INTEGRAÇÃO GPEA030API

    Sistemas Envolvidos

    Descrição dos sistemas envolvidos no contexto de negócio (e que serão envolvidos na integração).

    • Protheus (módulo de Gestão de Pessoal): Módulo responsável pela gestão do funcionário.
    • Quírons - NG

    Integração

    O objetivo desta integração é permitir que a área do RH ou área responsável pelo cadastro de funções do funcionário, envie os dados do cadastro de funções para o sistema da NG e assim reduzir o trabalho de inclusão manual de todas as informações dentro do sistema.

    • Benefícios 
      • Normalmente o colaborador responsável inclui as informações de cadastros de funções através de um arquivo (csv, txt) ou até mesmo manualmente. Com a interface de integração isso será feito de forma  automática.
      • Não terá um investimento alto de tempo para o cadastramento, pois os dados já serão enviados através da integração a cada requisição do sistema especialista.
    • Arquitetura (Tecnologia)
      • Toda integração entre o Protheus e o Quírons é feita por intermédio de comunicação direta com os Web Services (que são fixos)  REST(Representation State Transfer) utilizando o formato JSON (JavaScript  Object Notation) de serialização de dados, onde através da ativação do serviço do REST do Protheus esteja disponível para utilizar o serviço.
    • Premissas e Propriedades
      • O parceiro que será responsável pela requisição e transformação da informação recebida;
      • Cada produto deverá gerar um LOG de inclusão(RJ_USERLGI) ou alteração (RJ_USERLGA) de registros a fim de controlar os dados a serem integrados;
      • Na requisição, o parceiro deverá informar  através do preenchimento do parâmetro datemodified se desejar uma carga completa(deixar o parâmetro vazio) ou somente os dados que foram atualizados(Informando a data de alteração). Caso seja solicitada a carga, todos os dados serão enviados novamente. Caso seja  solicitado uma atualização, somente os dados com data igual ou posterior a data informada, serão transmitidos;
      • Será implementado um controle de paginação a fim de facilitar o envio da informação para o solicitante. Neste processo o solicitante deverá informar qual é o tamanho da informação solicitada e qual página ele solicita;
      • Cabe a integração informar se existem mais páginas a serem solicitadas;

    Ativação/Desativação da integração

    Por padrão esta integração estará em repositório, porém demanda realizar a devida configuração conforme abaixo:

    Controle de Ambiente

    Exige que os seguintes pontos sejam revisados:

    • Protheus com sua arquitetura devidamente estruturada.
    • Módulo Gestão de Pessoal com os dados do cadastro de funções devidamente inseridos.

    Controle de Versão

    O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

    Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das marcas e alinhamento com as diretivas definidas pelo Comitê de Integração TOTVS.

    Suporte

    O suporte aos recursos da Integração será de responsabilidade da linha Protheus, onde será analisada pela equipe de suporte da Totvs.

    Fluxo das Informações

    Esta integração traz a funcionalidade exclusivamente para exportação do cadastro de funções.

    Cadastro

    Esta integração contempla apenas a consulta e envio dos dados de funções.

    Processos

    A solicitante realizará o consumo da API com dados básicos que serão utilizados como parâmetros para consultar a base  e retornar um conjunto de informações pertinentes ao cadastro de funções.

    Limitações / Restrições Gerais

    • A integração não contemplará inclusão,alteração e exclusão de registros no Protheus, para isso o usuário deverá acessar o ERP e efetuar as devidas ações manualmente.
    • Cada produto deverá gerar um LOG de inclusão e alteração de registros a fim de controlar os dados a serem integrados;
    • A data de alteração do registro deverá ser enviada em cada processo, permitindo que o solicitante possa controlar essa informação;


    Como realizar a chamada da API REST

    Para realizar a integração com o parceiro TOTVS é necessário as informações básicas de consulta para retorno das funções desejados.

    • Preenchimento do EndPoint da API GPEA030API;
    • Utilizar a chamada do método Get e do Serviço positions;
    • Preenchimento dos parâmetros obrigatórios da API;

    Formatos de Data

    As Entradas e Saídas de dados tipo data(Date) acompanham o formato padrão YYYY-MM-DDThh:mm

    Parâmetros de Entrada:

    Parâmetro

    Valor de Exemplo

    Obrigatório

    Tipo Parâmetro

    Valor Default

    Descrição
    page 1 Não

    Integer

    query 1 Página que está sendo requisitada.
    pageSize 1 Não

    Integer

    query

    2000

    Quantidade de funções por página.
    datemodified 2001-01-01T18:25:43 Não String query
    Data que será utilizada como filtro para trazer funções com data de alteração (RJ_USERLGA) ou inclusão (RJ_USERLGI).
    branchId D MG 01 Sim String query

    companyId T1 Sim String query

    authorization

    não será informado pelos parâmetros REST Sim String header
    Configuração do parâmetro 

    Security = 1 no arquivo appserver.ini

    Parâmetros e Chamada do Método:

    Para a realização de testes foi utilizado a ferramenta SOAP UI e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

    {protocolo}://{host}/{api}//rh/v1/positions/

    Response da API:


    Response Positions

    {
        "items": [
            {
                "branchId": "D MG    ",
                "positionCode": "00001",
                "cbo": "252210",
                "companyId": "T1",
                "name": "FUNCAO PADRAO",
                "id": "T1|D MG    |00001|"
            },
            {
                "branchId": "D MG    ",
                "positionCode": "00002",
                "cbo": "",
                "companyId": "T1",
                "name": "MENOR APRENDIZ",
                "id": "T1|D MG    |00002|"
            },
            {
                "branchId": "D MG    ",
                "positionCode": "00003",
                "cbo": "456677",
                "companyId": "T1",
                "name": "GPE002-FUNCAO",
                "id": "T1|D MG    |00003|"
            }
        ],
        "hasNext": false
    }

    Situações de Erros Tratados

    O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros. Desta forma, foram criados alguns tratamentos de erros listados abaixo, cada um com sua respectiva mensagem e solução.

    Tratamento de erros de integração Protheus:

    Mensagens de Pré-Validação

    Erro

    Mensagem

    Solução

    400

    Campo RJ_USERLGI / RJ_USERLGA não foi encontrado.

    Campos _USERLGA/_USERLGI

    {
        "code": 400,
        "detailedMessage": "Campo USERLGA não foi encontrado: Entidade (SRJ)",
        "helpUrl": "https://tdn.totvs.com/x/BJuMHw",
        "message": "Campo USERLGA não foi encontrado: Entidade (SRJ)"
    }

    400

    A Filial é um parâmetro obrigatório.

    Quando o campo branchId está em branco.

    {
       "code": 400,
       "detailedMessage": "Falha ao validar as informações básicas da assinatura. Informação: branchId",
       "helpUrl": "https://tdn.totvs.com/x/BJuMHw",
       "message": "Falha ao validar as informações básicas da assinatura. Informação: branchId"
    }

    400 O Grupo de Empresa é um parâmetro obrigatório 

    Erro quando campo companyId está vazio.

    {
       "code": 400,
       "detailedMessage": "Falha ao validar as informações básicas da assinatura. Informação: companyId",
       "helpUrl": "https://tdn.totvs.com/x/BJuMHw",
       "message": "Falha ao validar as informações básicas da assinatura. Informação: companyId"
    }

    Checklist de suporte da aplicação

    Itens a serem verificados durante o atendimento:

    • Verificar se os pré-requisitos foram atendidos para a chamada da API;
    • Verificar se na chamada da API o EndPoint, o nome do serviço e todos os campos obrigatórios foram informados;
    • Verificar se o retorno da API apresenta algum erro tratado (códigos e mensagens de erro citados neste documento) e consultar a solução na mesma tabela que descreve o erro;
    • Em caso de Erro não tratado, verificar se possui alguma informação de banco de dados, conexão com o servidor ou algo que possa identificar a origem do problema.



    Relação de Tipos de Afastamento/Ausência - leaveOfAbsenceType - INTEGRAÇÃO GPEA430API 

    Sistemas Envolvidos

    Descrição dos sistemas envolvidos no contexto de negócio (e que serão envolvidos na integração).

    • Protheus (módulo de Gestão de Pessoal): Módulo responsável pela gestão do funcionário.
    • Quírons - NG

    Integração

    O objetivo desta integração é permitir que a área do RH ou área responsável pelos lançamentos de ausências, envie os dados do cadastro de tipos de afastamento para o sistema da NG e assim reduzir o trabalho de inclusão manual de todas as informações dentro do sistema.

    • Benefícios 
      • Normalmente o colaborador responsável ou empresa de benefícios, incluir as informações de cadastros de função através de um arquivo (csv, txt) ou até mesmo manualmente, com a interface de integração isso será feito de forma  automática.
      • Não terá um investimento alto de tempo para o cadastramento, pois os dados já serão enviados através da integração a cada requisição do sistema especialista.
    • Arquitetura (Tecnologia)
      • Toda integração entre o Protheus e o Sistema é feita por intermédio de comunicação direta com os Web Services(que são fixos)  REST(Representation State Transfer) utilizando o formato JSON(JavaScript  Object Notation) de serialização de dados, onde através da ativação do serviço do REST do Protheus esteja disponível para utilizar o serviço.
    • Premissas e Propriedades
      • O parceiro que será responsável pela requisição e transformação da informação recebida;
      • Cada produto deverá gerar um LOG de inclusão(RCM_USERGI) ou alteração (RCM_USERGA) de registros a fim de controlar os dados a serem integrados;
      • Na requisição, o parceiro deverá informar  através do preenchimento do parâmetro datemodified se desejar uma carga completa(deixar o parâmetro vazio) ou somente os dados que foram atualizados(Informando a data de alteração). Caso seja solicitada a carga, todos os dados deverão ser enviados novamente. Caso seja  solicitado uma atualização, somente os dados com data igual ou posterior a data informada, serão transmitidos;
      • A data de alteração do registro deverá ser enviada em cada processo, permitindo que o solicitante possa controlar essa informação;
      • Será implementado um controle de paginação a fim de facilitar o envio da informação para o solicitante. Neste processo o solicitante deverá informar qual é o tamanho da informação solicitada e qual página ela solicita;
      • Cabe a integração informar se existem mais páginas a serem solicitadas;

    Ativação/Desativação da integração

    Por padrão esta integração estará em repositório, porém demanda realizar a devida configuração conforme abaixo:

    Controle de Ambiente

    Exige que os seguintes pontos sejam revisados:

    • Protheus com sua arquitetura devidamente estruturada.
    • Módulo Gestão de Pessoal com os dados do cadastro de afastamento/ausências devidamente inseridos.

    Controle de Versão

    O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

    Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das marcas e alinhamento com as diretivas definidas pelo Comitê de Integração TOTVS.

    Suporte

    O suporte aos recursos da Integração será de responsabilidade da linha Protheus, onde será analisada pela equipe de suporte da Totvs.

    Fluxo das Informações

    Esta integração traz a funcionalidade exclusivamente para exportação do cadastro de Tipos de Afastamento/Ausências.

    Cadastro

    Esta integração contempla apenas a consulta e envio dos dados de Tipos de Afastamento/Ausências.

    Processos

    A solicitante realizará o consumo da API com dados básicos que serão utilizados como parâmetros para consultar a base  e retornar um conjunto de informações pertinentes ao cadastro de Tipos de Afastamento/Ausências.

    Limitações / Restrições Gerais

    • A integração não contemplará inclusão,alteração e exclusão de registros no Protheus, para isso o usuário deverá acessar o ERP e efetuar as devidas ações manualmente.
    • Cada produto deverá gerar um LOG de inclusão e alteração de registros a fim de controlar os dados a serem integrados;
    • A data de alteração do registro deverá ser enviada em cada processo, permitindo que o solicitante possa controlar essa informação;


    Como realizar a chamada da API REST

    Para realizar a integração com o parceiro TOTVS é necessário as informações básicas de consulta para retorno dos tipos de afastamento desejados.

    • Preenchimento do EndPoint da API GPEA430API;
    • Utilizar a chamada do método Get e do Serviço leaveOfAbsenceType;
    • Preenchimento dos parâmetros obrigatórios da API;

    Formatos de Data

    As Entradas e Saídas de dados tipo data(Date) acompanham o formato padrão YYYY-MM-DDThh:mm

    Parâmetros de Entrada:

    Parâmetro

    Valor de Exemplo

    Obrigatório

    Tipo Parâmetro

    Valor Default

    Descrição
    page 1 Não

    Integer

    query 1 Página que está sendo requisitada.
    pageSize 1 Não

    Integer

    query

    2000

    Quantidade de tipos de afastamento por página.
    datemodified 2001-01-01T18:25:43 Não String query
    Data que será utilizada como filtro para trazer tipos de afastamento com data de alteração (RCM_USERGA) ou inclusão (RCM_USERGI).
    branchId D MG 01 Sim String query

    companyId T1 Sim String query

    authorization

    não será informado pelos parâmetros REST Sim String header
    Configuração do parâmetro 

    Security = 1 no arquivo appserver.ini



    Parâmetros e Chamada do Método:

    Para a realização de testes foi utilizado a ferramenta SOAP UI e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

    {protocolo}://{host}/{api}//rh/v1/leaveOfAbsenceType/

    Response da API:


    Response LeaveOfAbsenceTypes

    {
        "items": [
            {
                "branchId": "D MG    ",
                "leaveOfAbsenceCode": "006",
                "esocialLeaveCode": "17",
                "companyId": "T1",
                "name": "Afastamento Temporario por Motivo de Licença-Maternidade Pago pela Empresa",
                "id": "T1|D MG    |006|"
            },
            {
                "branchId": "D MG    ",
                "leaveOfAbsenceCode": "007",
                "esocialLeaveCode": "",
                "companyId": "T1",
                "name": "Afastamento Temporario por Motivo de Licenca-Maternidade Pago pelo INSS",
                "id": "T1|D MG    |007|"
            },
            {
                "branchId": "D MG    ",
                "leaveOfAbsenceCode": "010",
                "esocialLeaveCode": "",
                "companyId": "T1",
                "name": "Licenca-Maternidade Decorrente de Adocao (120 Dias)",
                "id": "T1|D MG    |010|"
            }
        ],
        "hasNext": true
    }

    Situações de Erros Tratados

    O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros. Desta forma, foram criados alguns tratamentos de erros listados abaixo, cada um com sua respectiva mensagem e solução.

    Tratamento de erros de integração Protheus:

    Mensagens de Pré-Validação

    Erro

    Mensagem

    Solução

    400

    Campo RCM_USERGI / RCM_USERGA não foi encontrado.

    Campos _USERLGA/_USERLGI

    {
        "code": 400,
        "detailedMessage": "Campo USERGA não foi encontrado: Entidade (RCM)",
        "helpUrl": "https://tdn.totvs.com/x/BJuMHw",
        "message": "Campo USERGA não foi encontrado: Entidade (RCM)"
    }

    400

    A Filial é um parâmetro obrigatório.

    Quando o campo branchId está em branco.

    {
       "code": 400,
       "detailedMessage": "Falha ao validar as informações básicas da assinatura. Informação: branchId",
       "helpUrl": "https://tdn.totvs.com/x/BJuMHw",
       "message": "Falha ao validar as informações básicas da assinatura. Informação: branchId"
    }

    400 O Grupo de Empresa é um parâmetro obrigatório 

    Erro quando campo companyId está vazio.

    {
       "code": 400,
       "detailedMessage": "Falha ao validar as informações básicas da assinatura. Informação: companyId",
       "helpUrl": "https://tdn.totvs.com/x/BJuMHw",
       "message": "Falha ao validar as informações básicas da assinatura. Informação: companyId"
    }

    Checklist de suporte da aplicação

    Itens a serem verificados durante o atendimento:

    • Verificar se os pré-requisitos foram atendidos para a chamada da API;
    • Verificar se na chamada da API o EndPoint, o nome do serviço e todos os campos obrigatórios foram informados;
    • Verificar se o retorno da API apresenta algum erro tratado (códigos e mensagens de erro citados neste documento) e consultar a solução na mesma tabela que descreve o erro;
    • Em caso de Erro não tratado, verificar se possui alguma informação de banco de dados, conexão com o servidor ou algo que possa identificar a origem do problema.



    Relação de Tipos de Estabilidade stabilityType - INTEGRAÇÃO GPES053API


    Sistemas Envolvidos

    Descrição dos sistemas envolvidos no contexto de negócio (e que serão envolvidos na integração).

    • Protheus (módulo de Gestão de Pessoal): Módulo responsável pela gestão do funcionário.
    • Quírons - NG

    Integração

    O objetivo desta integração é permitir que a área do RH ou área responsável pelos períodos de estabilidade dos funcionários, envie os dados do cadastro de tipos de estabilidade para o sistema da NG e assim reduzir o trabalho de inclusão manual de todas as informações dentro do sistema.

    • Benefícios 
      • Normalmente o colaborador responsável inclui as informações de cadastros de tipos de estabilidade através de um arquivo (csv, txt) ou até mesmo manualmente. Com a interface de integração isso será feito de forma  automática.
      • Não terá um investimento alto de tempo para o cadastramento, pois os dados já serão enviados através da integração a cada requisição do sistema especialista.
    • Arquitetura (Tecnologia)
      • Toda integração entre o Protheus e o Quírons é feita por intermédio de comunicação direta com os Web Services (que são fixos)  REST(Representation State Transfer) utilizando o formato JSON (JavaScript  Object Notation) de serialização de dados, onde através da ativação do serviço do REST do Protheus esteja disponível para utilizar o serviço.
    • Premissas e Propriedades
      • O parceiro que será responsável pela requisição e transformação da informação recebida;
      • Cada produto deverá gerar um LOG de inclusão(RCC_USERGI) ou alteração (RCC_USERGA) de registros a fim de controlar os dados a serem integrados;
      • Na requisição, o parceiro deverá informar  através do preenchimento do parâmetro datemodified se desejar uma carga completa(deixar o parâmetro vazio) ou somente os dados que foram atualizados(Informando a data de alteração). Caso seja solicitada a carga, todos os dados serão enviados novamente. Caso seja  solicitado uma atualização, somente os dados com data igual ou posterior a data informada, serão transmitidos;
      • Será implementado um controle de paginação a fim de facilitar o envio da informação para o solicitante. Neste processo o solicitante deverá informar qual é o tamanho da informação solicitada e qual página ele solicita;
      • Cabe a integração informar se existem mais páginas a serem solicitadas;

    Ativação/Desativação da integração

    Por padrão esta integração estará em repositório, porém demanda realizar a devida configuração conforme abaixo:

    Controle de Ambiente

    Exige que os seguintes pontos sejam revisados:

    • Protheus com sua arquitetura devidamente estruturada.
    • Módulo Gestão de Pessoal com os dados do cadastro de estabilidade devidamente inseridos.

    Controle de Versão

    O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

    Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das marcas e alinhamento com as diretivas definidas pelo Comitê de Integração TOTVS.

    Suporte

    O suporte aos recursos da Integração será de responsabilidade da linha Protheus, onde será analisada pela equipe de suporte da Totvs.

    Fluxo das Informações

    Esta integração traz a funcionalidade exclusivamente para exportação do cadastro de Tipos de Estabilidade

    Cadastro

    Esta integração contempla apenas a consulta e envio dos dados de Tipos de Estabilidade.

    Processos

    A solicitante realizará o consumo da API com dados básicos que serão utilizados como parâmetros para consultar a base  e retornar um conjunto de informações pertinentes ao cadastro de Tipos de Estabilidade.

    Limitações / Restrições Gerais

    • A integração não contemplará inclusão,alteração e exclusão de registros no Protheus, para isso o usuário deverá acessar o ERP e efetuar as devidas ações manualmente.
    • Cada produto deverá gerar um LOG de inclusão e alteração de registros a fim de controlar os dados a serem integrados;
    • A data de alteração do registro deverá ser enviada em cada processo, permitindo que o solicitante possa controlar essa informação;


    Atenção

    Importante: Devido à característica da rotina de Manutenção de Tabelas (GPEA320) em que a cada alteração os registros são regravados, o campo RCC_USERGA de todos os registros daquela filial serão renovado a cada manutenção efetuada.

    Como realizar a chamada da API REST

    Para realizar a integração com o parceiro TOTVS é necessário as informações básicas de consulta para retorno dos tipos de estabilidade desejados.

    • Preenchimento do EndPoint da API GPES053API;
    • Utilizar a chamada do método Get e do Serviço stabilityTypes;
    • Preenchimento dos parâmetros obrigatórios da API;

    Formatos de Data

    As Entradas e Saídas de dados tipo data(Date) acompanham o formato padrão YYYY-MM-DDThh:mm

    Parâmetros de Entrada:

    Parâmetro

    Valor de Exemplo

    Obrigatório

    Tipo Parâmetro

    Valor Default

    Descrição
    page 1 Não

    Integer

    query 1 Página que está sendo requisitada.
    pageSize 1 Não

    Integer

    query

    2000

    Quantidade de tipos de estabilidade por página.
    datemodified 2001-01-01T18:25:43 Não String query
    Data que será utilizada como filtro para trazer tipos de estabilidade com data de alteração (RCC_USERGA) ou inclusão (RCC_USERGI).
    branchId D MG 01 Sim String query

    companyId T1 Sim String query

    authorization

    não será informado pelos parâmetros REST Sim String header
    Configuração do parâmetro 

    Security = 1 no arquivo appserver.ini



    Parâmetros e Chamada do Método:

    Para a realização de testes foi utilizado a ferramenta SOAP UI e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

    {protocolo}://{host}/{api}//rh/v1/stabilityType/

    Response da API:


    Response StabilityTypes

    {
        "items": [
            {
                "branchId": "D MG    ",
                "stabilityCode": "S01",
                "companyId": "T1",
                "name": "MEMBRO DA CIPA",
                "id": "T1|D MG    |S01"
            },
            {
                "branchId": "D MG    ",
                "stabilityCode": "S04",
                "companyId": "T1",
                "name": "NAO OPTANTES PELO FGTS(ESTABILIDADE DECENAL)",
                "id": "T1|D MG    |S04"
            },
            {
                "branchId": "D MG    ",
                "stabilityCode": "S05",
                "companyId": "T1",
                "name": "ACIDENTE DE TRABALHO",
                "id": "T1|D MG    |S05"
            }
        ],
        "hasNext": true
    }

    Situações de Erros Tratados

    O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros. Desta forma, foram criados alguns tratamentos de erros listados abaixo, cada um com sua respectiva mensagem e solução.

    Tratamento de erros de integração Protheus:

    Mensagens de Pré-Validação

    Erro

    Mensagem

    Solução

    400

    Campo RCC_USERGI / RCC_USERGA não foi encontrado.

    Campos _USERLGA/_USERLGI

    {
        "code": 400,
        "detailedMessage": "Campo USERGA não foi encontrado: Entidade (RCC)",
        "helpUrl": "https://tdn.totvs.com/x/BJuMHw",
        "message": "Campo USERGA não foi encontrado: Entidade (RCC)"
    }

    400

    A Filial é um parâmetro obrigatório.

    Quando o campo branchId está em branco.

    {
       "code": 400,
       "detailedMessage": "Falha ao validar as informações básicas da assinatura. Informação: branchId",
       "helpUrl": "https://tdn.totvs.com/x/BJuMHw",
       "message": "Falha ao validar as informações básicas da assinatura. Informação: branchId"
    }

    400 O Grupo de Empresa é um parâmetro obrigatório 

    Erro quando campo companyId está vazio.

    {
       "code": 400,
       "detailedMessage": "Falha ao validar as informações básicas da assinatura. Informação: companyId",
       "helpUrl": "https://tdn.totvs.com/x/BJuMHw",
       "message": "Falha ao validar as informações básicas da assinatura. Informação: companyId"
    }

    Checklist de suporte da aplicação

    Itens a serem verificados durante o atendimento:

    • Verificar se os pré-requisitos foram atendidos para a chamada da API;
    • Verificar se na chamada da API o EndPoint, o nome do serviço e todos os campos obrigatórios foram informados;
    • Verificar se o retorno da API apresenta algum erro tratado (códigos e mensagens de erro citados neste documento) e consultar a solução na mesma tabela que descreve o erro;
    • Em caso de Erro não tratado, verificar se possui alguma informação de banco de dados, conexão com o servidor ou algo que possa identificar a origem do problema.

    Relação de Treinamentos - classes - INTEGRAÇÃO TRMA050API 

    Sistemas Envolvidos

    Descrição dos sistemas envolvidos no contexto de negócio (e que serão envolvidos na integração).

    • Protheus (módulo Treinamentos): Módulo responsável pela gestão dos cursos, treinamentos dentre outros cadastros pertinentes aos colaboradores.
    • Quírons - NG

    Integração

    O objetivo desta integração é permitir que a área do RH ou área responsável pelos agendamentos de treinamento, envie os dados do cadastro de treinamento para o sistema da NG e assim reduzir o trabalho de inclusão manual de todas as informações dentro do sistema.

    • Benefícios 
      • Normalmente o colaborador responsável inclui as informações de cadastros de treinamentos através de um arquivo (csv, txt) ou até mesmo manualmente. Com a interface de integração isso será feito de forma  automática.
      • Não terá um investimento alto de tempo para o cadastramento, pois os dados já serão enviados através da integração a cada requisição do sistema especialista.
    • Arquitetura (Tecnologia)
      • Toda integração entre o Protheus e o Quírons é feita por intermédio de comunicação direta com os Web Services (que são fixos)  REST(Representation State Transfer) utilizando o formato JSON (JavaScript  Object Notation) de serialização de dados, onde através da ativação do serviço do REST do Protheus esteja disponível para utilizar o serviço.
    • Premissas e Propriedades
      • O parceiro que será responsável pela requisição e transformação da informação recebida;
      • Cada produto deverá gerar um LOG de inclusão(RA2_USERGI) ou alteração (RA2_USERGA) de registros a fim de controlar os dados a serem integrados;
      • Na requisição, o parceiro deverá informar  através do preenchimento do parâmetro datemodified se desejar uma carga completa(deixar o parâmetro vazio) ou somente os dados que foram atualizados(Informando a data de alteração). Caso seja solicitada a carga, todos os dados serão enviados novamente. Caso seja  solicitado uma atualização, somente os dados com data igual ou posterior a data informada, serão transmitidos;
      • Será implementado um controle de paginação a fim de facilitar o envio da informação para o solicitante. Neste processo o solicitante deverá informar qual é o tamanho da informação solicitada e qual página ele solicita;
      • Cabe a integração informar se existem mais páginas a serem solicitadas;

    Ativação/Desativação da integração

    Por padrão esta integração estará em repositório, porém demanda realizar a devida configuração conforme abaixo:

    Controle de Ambiente

    Exige que os seguintes pontos sejam revisados:

    • Protheus com sua arquitetura devidamente estruturada.
    • Módulo Gestão de Pessoal com os dados do cadastro de treinamentos devidamente inseridos.

    Controle de Versão

    O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

    Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das marcas e alinhamento com as diretivas definidas pelo Comitê de Integração TOTVS.

    Suporte

    O suporte aos recursos da Integração será de responsabilidade da linha Protheus, onde será analisada pela equipe de suporte da Totvs.

    Fluxo das Informações

    Esta integração traz a funcionalidade exclusivamente para exportação do cadastro de treinamentos.

    Cadastro

    Esta integração contempla apenas a consulta e envio dos dados de treinamentos.

    Processos

    A solicitante realizará o consumo da API com dados básicos que serão utilizados como parâmetros para consultar a base  e retornar um conjunto de informações pertinentes ao cadastro de treinamentos.

    Limitações / Restrições Gerais

    • A integração não contemplará inclusão, alteração e exclusão de registros no Protheus, para isso o usuário deverá acessar o ERP e efetuar as devidas ações manualmente.
    • Cada produto deverá gerar um LOG de inclusão e alteração de registros a fim de controlar os dados a serem integrados;
    • A data de alteração do registro deverá ser enviada em cada processo, permitindo que o solicitante possa controlar essa informação;

    Como realizar a chamada da API REST

    Para realizar a integração com o parceiro TOTVS é necessário as informações básicas de consulta para retorno dos treinamentos desejados.

    • Preenchimento do EndPoint da API TRMA050API;
    • Utilizar a chamada do método Get e do Serviço classes;
    • Preenchimento dos parâmetros obrigatórios da API;

    Formatos de Data

    As Entradas e Saídas de dados tipo data(Date) acompanham o formato padrão YYYY-MM-DDThh:mm

    Parâmetros de Entrada:

    Parâmetro

    Valor de Exemplo

    Obrigatório

    Tipo Parâmetro

    Valor Default

    Descrição
    page 1 Não

    Integer

    query 1 Página que está sendo requisitada.
    pageSize 1 Não

    Integer

    query

    2000

    Quantidade de treinamentos por página.
    datemodified 2001-01-01T18:25:43 Não String query
    Data que será utilizada como filtro para trazer treinamentos com data de alteração (RA2_USERGA) ou inclusão (RA2_USERGI).
    branchId D MG 01 Sim String query

    companyId T1 Sim String query

    authorization

    não será informado pelos parâmetros REST Sim String header
    Configuração do parâmetro 

    Security = 1 no arquivo appserver.ini



    Parâmetros e Chamada do Método:

    Para a realização de testes foi utilizado a ferramenta SOAP UI e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

    {protocolo}://{host}/{api}//rh/v2/classes/

    Response da API:


    Response classes

    {
        "items": [
            {
                "branchId": "D MG    ",
                "classCode": "0001",
                "esocialTrainingCode": "0097",
                "companyId": "T1",
                "name": "CURSO 001",
                "id": "T1|D MG    |0001|"
            },
            {
                "branchId": "D MG    ",
                "classCode": "0002",
                "esocialTrainingCode": "0101",
                "companyId": "T1",
                "name": "CURSO 002",
                "id": "T1|D MG    |0002|"
            },
            {
                "branchId": "D MG    ",
                "classCode": "0001",
                "esocialTrainingCode": "0502",
                "companyId": "T1",
                "name": "CURSO 001",
                "id": "T1|D MG    |0001|"
            }
        ],
        "hasNext": true
    }

    Situações de Erros Tratados

    O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros. Desta forma, foram criados alguns tratamentos de erros listados abaixo, cada um com sua respectiva mensagem e solução.

    Tratamento de erros de integração Protheus:

    Mensagens de Pré-Validação

    Erro

    Mensagem

    Solução

    400

    Campo RA2_USERGI / RA2_USERGA não foi encontrado.

    Campos _USERLGA/_USERLGI

    {
        "code": 400,
        "detailedMessage": "Campo USERGA não foi encontrado: Entidade (RA2)",
        "helpUrl": "https://tdn.totvs.com/x/BJuMHw",
        "message": "Campo USERGA não foi encontrado: Entidade (RA2)"
    }

    400

    A Filial é um parâmetro obrigatório.

    Quando o campo branchId está em branco.

    {
       "code": 400,
       "detailedMessage": "Falha ao validar as informações básicas da assinatura. Informação: branchId",
       "helpUrl": "https://tdn.totvs.com/x/BJuMHw",
       "message": "Falha ao validar as informações básicas da assinatura. Informação: branchId"
    }

    400 O Grupo de Empresa é um parâmetro obrigatório 

    Erro quando campo companyId está vazio.

    {
       "code": 400,
       "detailedMessage": "Falha ao validar as informações básicas da assinatura. Informação: companyId",
       "helpUrl": "https://tdn.totvs.com/x/BJuMHw",
       "message": "Falha ao validar as informações básicas da assinatura. Informação: companyId"
    }

    Checklist de suporte da aplicação

    Itens a serem verificados durante o atendimento:

    • Verificar se os pré-requisitos foram atendidos para a chamada da API;
    • Verificar se na chamada da API o EndPoint, o nome do serviço e todos os campos obrigatórios foram informados;
    • Verificar se o retorno da API apresenta algum erro tratado (códigos e mensagens de erro citados neste documento) e consultar a solução na mesma tabela que descreve o erro;
    • Em caso de Erro não tratado, verificar se possui alguma informação de banco de dados, conexão com o servidor ou algo que possa identificar a origem do problema.



    Controle de Adicionais - additional -  INTEGRAÇÃO GPEAADIAPI  

    Sistemas Envolvidos

    • Protheus (módulo  Gestão de Pessoal): Módulo responsável pela gestão dos dados dos funcionários, folha de pagamento e dentre outros cadastros pertinentes aos colaboradores.

    • Quírons - NG

    Integração

    O objetivo desta integração é permitir que o RH ou área responsável pelo Gestão de Pessoal do Protheus, receba os dados do Controle de Adicionais dos funcionários de outros sistemas especializados, reduzindo assim o trabalho de inclusão/alteração/exclusão manual dessas informações dentro do sistema;

    • Benefícios
      • Não terá um investimento alto de tempo para o cadastramento, pois os dados já serão enviados, editados ou excluídos através da integração a cada requisição do sistema especialista através da API de Adicional.
      • A informação será atualizada de forma automática, facilitando que conferência e confiabilidade dos dados recebidos.
    • Arquitetura (Tecnologia)

    Toda integração entre o Protheus e o Sistema é feita por intermédio de comunicação direta com os Web Services(que são fixos) REST(Representation State Transfer) utilizando o formato JSON(JavaScript  Object Notation) de serialização de dados, onde através da ativação do serviço do REST do Protheus esteja disponível para utilizar o serviço.

    Escopo

    Por intermédio desta integração será disponibilizada a seguinte funcionalidade:

    • Atualização dos Adicionais de Periculosidade e Insalubridade do funcionário no módulo SIGAGPE;

    Fora do escopo

    • Automatização de consultas dos adicionais do funcionário
    • Importação de base cadastral - dados do Funcionário,

    Pré-requisitos instalação / implantação / utilização

    Versões mínimas do Protheus: 12.1.23

    • Possuir acesso à Internet, caso o sistema que venha a utilizar a integração com a aplicação Protheus.
    • Estrutura de rede estável, para que haja tráfego de dados sem interrupção.
    • Protheus devidamente configurado e serviço Rest habilitado em seu server.
    Instalação/Atualização

    Este tópico tem por objetivo orientar a instalação da integração, visando o seu funcionamento completo.

    Instalação de produtos ou ferramentas necessárias podem referenciar outros documentos existentes, desde que estejam disponíveis no repositório de documentação da TOTVS ou sejam enviados junto com o documento da integração em si.

    As informações mínimas necessárias para este tópico são:

    Ativação/Desativação da integração

    Por padrão esta integração estará em repositório, porém demanda realizar a devida configuração conforme abaixo:

    Controle de Ambiente

    Exige que os seguintes pontos sejam revisados:

    • Protheus com sua arquitetura devidamente estruturada.
    • Módulo de Gestão de Pessoal (SIGAGPE) com suas entidades base, devidamente populadas por dados que no momento da integração serão utilizados na criação do registro de adicional. (Para melhor compreensão, analise o cadastro disponível dentro do sistema e verifique os campos que possuem consultas em outras tabelas se as mesmas estão com os seus dados devidamente cadastrados).

    Controle de Versão

    O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

    Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das marcas e alinhamento com as diretivas definidas pelo Comitê de Integração TOTVS.

    Suporte

    O suporte aos recursos da Integração será de responsabilidade da linha Protheus, onde será analisada pela equipe de suporte da Totvs.

    Fluxo das Informações

    Esta integração traz a funcionalidade exclusivamente à área de Gestão de Pessoal, no processo de alteração dos adicionais do funcionario.

    Processos

    O Sistema requisitante enviará as informações via json para a interface de integração, desta forma serão atualizados os dados de periculosidade e insalubridade dentro do cadastro do funcionário no Protheus, caso tenha êxito na geração do registro, será retornada a mesma estrutura json recebida, acompanhada de uma nova tag chamada id, que será uma chave única composta de informações da entidade dentro do sistema.  Desta forma será confirmada sua gravação, caso contrário enviará as informações de inconsistências que serão citadas nos próximos tópicos.

    Limitações / Restrições Gerais
    • Com o objetivo de manter a estrutura e a agilidade da estrutura Rest, o Web Service Rest receberá o registro individual de cada funcionário.
    Como realizar a chamada da API REST

    Para realizar a integração com o parceiro TOTVS são necessárias as informações básicas de consulta para retorno do funcionário desejado.

    • Preenchimento do EndPoint da API GPEAADIPI;
    • Utilizar a chamada do método Put  e do Serviço additional;
    • Preenchimento dos parâmetros obrigatórios da API.



    Parâmetros de Entrada PUT:

    Parâmetro

    Valor de Exemplo

    Obrigatório

    Tipo

    Valor Default

    Descrição
    authorization  usuario:senha Sim

    header


    autenticação é requerida para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
    additionalId

    T1; D MG 01 ; T1|D MG 01 |000001

    Sim URL Parameters

    Composição da string a ser enviada, deve ser ser composta por "GRUPO DE EMPRESA;FILIAL;CHAVE FUNCIONARIO".

    content {
    "companyId":"T1",
    "branchId": "D MG 01 ",
    "employeeId":"T1|D MG 01 |160001",
    "unhealthyDegree1": "1",
    "dangerousness1": "2"
    }
    sim body

    Estrutura json com informações de periculosidade e insalubridade do funcionário:

    • dangerousness:
    • unhealthyDegree

    Parâmetros e Chamada do Método:

    Para a realização de testes foi utilizado a ferramenta POSTMAN e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

    {protocolo}://{host}/{api}/rh/v1/additional/{additionalId}

    Exemplo: http://localhost:5192/api/rh/v1/additional/T1;M SP 01 ;T1|M SP 01 |600001


    Dados utilizados da API

    Por ser uma estrutura única para todas as linhas, cada linha utilizará os campos pertinentes aos seus ambientes.

    Propriedade API REST CAMPO PROTHEUS DESCRIÇÃO Formato
    companyId M0_CODIGO Informações de acesso ao sistema, campo contém informação do grupo de empresa
    branchId RA_FILIAL Informações de acesso ao sistema, campo compõe Empresa+Unidade de Negócio+ Filial
    employeeId RA_MAT Chave do Funcionário. Empresa|Filial|Matrícula
    dangerousness RA_ADCPERI Periculosidade "1"
    unhealthyDegree RA_ADCINS Insalubridade Grau "2"

    Situações Tratadas

    O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros.
    Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.


    Mensagens Validação

    Erro

    Mensagem

    Solução

    API RESPONSE

    200

    Atualizado com sucesso.

    Registro alterado com sucesso.

    {
    "companyId":"T1",
    "branchId": "D MG 01 ",
    "employeeId":"T1|D MG 01 |160001",
    "unhealthyDegree1": "1",
    "dangerousness1": "2",

    "id": "T1;D MG 01 ; T1|D MG 01 | 160001"

    }





    400

    Erro na validação do recebimento da mensagem.

    Verificar se as propriedade URL Parameters additionalId está preenchida e com dados válidos no pacote enviado.

    1. Dados de Empresa e Filial,
    2. Dados de Filial e Matrícula,
    {
        "code": 400,
        "detailedMessage": "Informação addionalId ausente ou inválida",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    500

    Ocorreu uma falha no retorno da informação.

    É necessário avaliar se o servidor está funcionando corretamente.
    {
       "errorCode": 500,
       "errorMessage": "Ocorreu uma falha no retorno da informação."
    }


    OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.

    Checklist de suporte da aplicação

    Itens a serem verificados durante o atendimento:

    • Verificar se os pré-requisitos foram atendidos para a chamada da API;
    • Verificar se na chamada da API o EndPoint, o nome do serviço e todos os campos obrigatórios foram informados;
    • Verificar se o retorno da API apresenta algum erro tratado (códigos e mensagens de erro citados neste documento) e consultar a solução na mesma tabela que descreve o erro;
    • Em caso de erro não tratado, verificar se possui alguma informação de banco de dados, conexão com o servidor ou algo que possa identificar a origem do problema.


    Anexos



    Controle de Estabilidade - stabilityControl - INTEGRAÇÃO GPEA923API -


    Sistemas Envolvidos

    • Descrição dos sistemas envolvidos no contexto de negócio (e que serão envolvidos na integração).

      • Protheus (módulo de Gestão de Pessoal): Módulo responsável pela gestão do funcionário.
      • Quírons - NG

    Integração

    O objetivo desta integração é permitir que o RH ou área responsável pelo Gestão de Pessoal do Protheus, receba os dados do Controle de Estabilidade dos funcionários de outros sistemas especializados, reduzindo assim o trabalho de inclusão/alteração/exclusão manual dessas informações dentro do sistema;

    • Benefícios
      • Não terá um investimento alto de tempo para o cadastramento, pois os dados já serão enviados, editados ou excluídos através da integração a cada requisição do sistema especialista através da API de Estabilidade.
      • A informação será atualizada de forma automática, facilitando que conferência e confiabilidade dos dados recebidos.
    • Arquitetura (Tecnologia)

    Toda integração entre o Protheus e o Sistema é feita por intermédio de comunicação direta com os Web Services(que são fixos) REST(Representation State Transfer) utilizando o formato JSON(JavaScript  Object Notation) de serialização de dados, onde através da ativação do serviço do REST do Protheus esteja disponível para utilizar o serviço.

    Escopo

    Por intermédio desta integração será disponibilizada a seguinte funcionalidade:

    • Manutenção do Período de Estabilidade do funcionário no módulo SIGAGPE;

    Fora do escopo

    • Automatização de consultas de Período de Estabilidade,
    • Importação de base cadastral - dados do Funcionário,
    • Informações do Período de Estabilidade que não se enquadram dentro da tabela de Período de Estabilidade


    Pré-requisitos instalação/implantação/utilização

    • Versões mínimas do Protheus: 12.1.23
    • Possuir acesso à Internet, caso o sistema que venha a utilizar a integração com a aplicação Protheus.
    • Estrutura de rede estável, para que haja tráfego de dados sem interrupção.
    • Protheus devidamente configurado e serviço Rest habilitado em seu server.


    Instalação/Atualização

    Este tópico tem por objetivo orientar a instalação da integração, visando o seu funcionamento completo.

    Instalação de produtos ou ferramentas necessárias podem referenciar outros documentos existentes, desde que estejam disponíveis no repositório de documentação da TOTVS ou sejam enviados junto com o documento da integração em si.

    As informações mínimas necessárias para este tópico são:

    Ativação/Desativação da integração

    Por padrão esta integração estará em repositório, porém demanda realizar a devida configuração conforme abaixo:

    Controle de Ambiente

    Exige que os seguintes pontos sejam revisados:

    • Protheus com sua arquitetura devidamente estruturada.
    • Módulo de Gestão de Pessoal (SIGAGPE) com suas entidades base, devidamente populadas por dados que no momento da integração serão utilizados na criação do registro de estabilidade. (Para melhor compreensão, analise o cadastro disponível dentro do sistema e verifique os campos que possuem consultas em outras tabelas se as mesmas estão com os seus dados devidamente cadastrados).

    Controle de Versão

    O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

    Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das marcas e alinhamento com as diretivas definidas pelo Comitê de Integração TOTVS.

    Suporte

    O suporte aos recursos da Integração será de responsabilidade da linha Protheus, onde será analisada pela equipe de suporte da Totvs.

    Fluxo das Informações

    Esta integração traz a funcionalidade exclusivamente à área de Gestão de Pessoal, no processo de cadastramento (inclusão/alteração/exclusão) de Período de Estabilidade.

    Cadastro

    Esta integração contempla apenas o cadastramento(inclusão/alteração/exclusão) do Período de Estabilidade dentro do módulo SIGAGPE.

    Processos

    O Sistema requisitante enviará as informações via json para a interface de integração, desta forma será gerado um novo registro na tabela de Período de Estabilidade no Protheus, caso tenha êxito na geração do registro, será retornada a mesma estrutura de json recebida, acompanhada de uma nova tag chamada id, acompanhada de uma nova tag chamada id, que será uma chave única composta de informações da entidade dentro do sistema.  Desta forma será confirmada sua gravação, caso contrário enviará as informações de inconsistências que serão citadas nos próximos tópicos.


    Limitações / Restrições Gerais

    • Com o objetivo de manter a estrutura e a agilidade da estrutura Rest, o Web Service Rest receberá o registro individual de cada Período de Estabilidade.


    Como realizar a chamada da API REST

    Para realizar a integração com o parceiro TOTVS são necessárias as informações básicas de consulta para retorno do funcionário desejado.

    • Preenchimento do EndPoint da API GPEA923API;
    • Utilizar a chamada do método Post, Put e Delete e do Serviço stabilityControl;
    • Preenchimento dos parâmetros obrigatórios da API.

    Parâmetros de Entrada POST:

    Parâmetro

    Valor de Exemplo

    Obrigatório

    Tipo

    Valor Default

    Descrição
    authorization  usuario:senha Sim

    header


    autenticação é requerida para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
    content {
    "companyId":"T1",
    "branchId": "D MG 01 ",
    "employeeId":"T1|D MG 01 |160001",
    "startDate": "2020-06-02T10:10:10",
    "stabilityCode": "T1|D MG |S01"
    }
    Sim body

    Estrutura json com informações do período de estabilidade do funcionário:

    Dados de preparação de ambiente:

    • companyId: Grupo de empresa
    • branchId: Empresa+Unidade de negócio+Filial

    Dados de Período de Estabilidade:

    • employeeId: Informação pertinente ao funcionário.
    • startDate: Data do Início do Período de Estabilidade.
    • endDate: Data do Final do Período de Estabilidade.
    • stabilityCode: Tipo de Estabilidade registrado.

    Parâmetros e Chamada do Método:

    Para a realização de testes foi utilizado a ferramenta POSTMAN e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

    {protocolo}://{host}/{api}/api/rh/v1/stabilityControl


    Dados utilizados da API

    Por ser uma estrutura única para todas as linhas, cada linha utilizará os campos pertinentes aos seus ambientes.

    Propriedade API REST CAMPO PROTHEUS DESCRIÇÃO Formato
    companyId
    Informações de acesso ao sistema, campo contém informação do grupo de empresa
    branchId RFX_FILIAL Informações de acesso ao sistema, campo compõe Empresa+Unidade de Negócio+ Filial "D MG 01 "
    employeeId RFX_MAT Chave do Funcionário "T1|D MG 01 |000001"
    startDate RFX_DATAI Data de Início do Período "2020-01-01T18:25:43"
    endDate RFX_DATAF Data de término do Período "2020-01-01T18:25:43"
    stabilityCode

    RFX_TPESTB

    Chave do Tipo de Estabilidade "T1|D MG |S01"

    Situações Tratadas

    O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros.
    Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.


    Mensagens Validação

    Erro

    Mensagem

    Solução

    API RESPONSE
    201 Registro criado.
    {
        "companyId": "T1",
        "branchId": "D MG 01 ",
        "startDate": "2020-01-01T18:25:43",
        "employeeId": "T1|D MG 01 |000001",
        "stabilityCode": "T1|D MG    |S01",
        "id": "T1;D MG 01 ;T1|D MG 01 |000001;2020-01-01T18:25:43;T1|D MG    |S01"
    }
    400 Erro na validação do recebimento da mensagem. Verificar se as propriedades json obrigatórias (companyID , branchId , employeeIdstartDate, stabilityCode) estão preenchidas.
    {
        "code": 400,
        "detailedMessage": "Verifique o conteúdo da TAG (employeeId) pois ela é obrigatória para a manipulação deste processo.\r\n\r\n",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    500

    Ocorreu uma falha no retorno da informação.

    É necessário avaliar se o servidor está funcionando corretamente.
    {
        "code": 500,
        "detailedMessage": "Ocorreu uma falha no retorno da informação.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": Descrição do erro.
    }

    OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.


    Parâmetros de Entrada PUT:

    Parâmetro

    Valor de Exemplo

    Obrigatório

    Tipo

    Valor Default

    Descrição
    authorization  usuario:senha Sim

    header


    autenticação é requerida para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
    stabilityId

    T1;D MG 01 ;T1|D MG 01 |160001;2020-06-18T10:10:10;T1|D MG |S01

    Sim request

    Composição da string a ser enviada, deve ser ser composta por "GRUPO DE EMPRESA;FILIAL;CHAVEFUNCIONARIO;DATA DE INÍCIO; CHAVE TIPODEESTABILIDADE".

    content

    {
    "companyId":"T1",
    "branchId": "D MG 01 ",
    "employeeId":"T1|D MG 01 |160001",
    "startDate": "2020-06-02T10:10:10",

    "endDate": "2020-06-02T10:10:10",
    "stabilityCode": "T1|D MG |S01"
    }

    sim body

    Estrutura json com informações do período de estabilidade:

    Dados de preparação de ambiente:

    • companyId: Grupo de empresa
    • branchId: Empresa+Unidade de negócio+Filial

    Dados de Período de Estabilidade:

    • employeeId: Informação pertinente ao funcionário.
    • startDate: Data do Início do Período de Estabilidade.
    • stabilityCode: Tipo de Estabilidade registrado.

    Parâmetros e Chamada do Método:

    Para a realização de testes foi utilizado a ferramenta POSTMAN e após a configuração do server Protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

    {protocolo}://{host}/{api}/api/rh/v1/stabilityControl{stabilityId}



    Dados utilizados da API

    Por ser uma estrutura única para todas as linhas, cada linha utilizará os campos pertinentes aos seus ambientes.

    Propriedade API REST CAMPO PROTHEUS DESCRIÇÃO Formato
    companyId
    Informações de acesso ao sistema, campo contém informação do grupo de empresa
    branchId RFX_FILIAL Informações de acesso ao sistema, campo compõe Empresa+Unidade de Negócio+ Filial "D MG 01"
    employeeId RFX_MAT Chave do Funcionário. "T1|D MG 01 |000001"
    startDate RFX_DATAI Data do Início do Período "2020-01-01T18:25:43"
    startDate RFX_DATAF Data do final do Período "2020-01-01T18:25:43"
    stabilityCode RFX_TPESTB Chave do Tipo de Estabilidade "T1|D MG |S01"

    Situações Tratadas

    O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros.
    Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.


    Mensagens Validação

    Erro

    Mensagem

    Solução

    API RESPONSE

    200

    Atualizado com sucesso.

    Registro alterado com sucesso.

    {
    "companyId":"T1",
    "branchId": "D MG 01 ",
    "employeeId":"T1|D MG 01 |160001",
    "startDate": "2020-06-02T10:10:10",
    "endDate": "2020-06-03T10:10:10",
    "stabilityCode": "T1|D MG |S01",
    "id": "T1;D MG 01 ;2020-06-02T10:10:10;10:10;T1|D MG 01 |160001"
    }

    400

    Erro na validação do recebimento da mensagem.

    Verificar se as propriedade json stabilityId está preenchida e com dados válidos no pacote enviado.

    1. Dados de Empresa e Filial,
    2. Dados de Filial e Matrícula,
    3. Formato da Data de Início,
    4. Tipo de Estabilidade.
    {
        "code": 400,
        "detailedMessage": "Informação stabilityId ausente ou inválida.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    500

    Ocorreu uma falha no retorno da informação.

    É necessário avaliar se o servidor está funcionando corretamente.
    {
        "code": 500,
        "detailedMessage": "Ocorreu uma falha no retorno da informação.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": Descrição do erro.
    }


    OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.



    Parâmetros de Entrada DELETE:

    Parâmetro

    Valor de Exemplo

    Obrigatório

    Tipo

    Valor Default

    Descrição
    authorization  usuario: senha Sim

    header


    autenticação é importante para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
    stabilityId

    T1;D MG 01 ;T1|D MG 01 |160001;2020-06-18T10:10:10;T1|D MG |S01

    Sim query

    Composição da string a ser enviada, deve ser ser composta por "GRUPODEEMPRESA;FILIAL;CHAVEFUNCIONARIO;DATAINICIO;CHAVETIPODEESTABILIDADE".

    Parâmetros e Chamada do Método:

    Para a realização de testes foi utilizado a ferramenta POSTMAN e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

    {protocolo}://{host}/{api}/api/rh/v1/stabilityControl{stabilityId}

    Situações Tratadas

    O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros.
    Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.


    Mensagens Validação

    Erro

    Mensagem

    Solução

    API RESPONSE
    200 Operação realizada com sucesso. Registro foi deletado com sucesso.
    {
        "code": "200",
        "description": "Operação realizada com sucesso!"
    }

    400

    Erro na validação do recebimento da mensagem.

    Verificar se as propriedade json stabilityId está preenchida e com dados válidos no pacote enviado.

    1. Dados de Empresa e Filial,
    2. Dados de Filial e Matrícula,
    3. Formato da Data de Início,
    4. Tipo de Estabilidade.
    {
        "code": 400,
        "detailedMessage": "Informação stabilityId ausente ou inválida.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    500

    Erro no acesso ao Endpoint.

    É necessário avaliar se o servidor está funcionando corretamente.
    {
        "code": 500,
        "detailedMessage": "Ocorreu uma falha no retorno da informação.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": Descrição do erro.
    }


    OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.

    Checklist de suporte da aplicação

    Itens a serem verificados durante o atendimento:

    • Verificar se os pré-requisitos foram atendidos para a chamada da API;
    • Verificar se na chamada da API o EndPoint, o nome do serviço e todos os campos obrigatórios foram informados;
    • Verificar se o retorno da API apresenta algum erro tratado (códigos e mensagens de erro citados neste documento) e consultar a solução na mesma tabela que descreve o erro;
    • Em caso de erro não tratado, verificar se possui alguma informação de banco de dados, conexão com o servidor ou algo que possa identificar a origem do problema.


    Anexos



    Controle de Abonos - AllowanceControl - INTEGRAÇÃO PONA350API 


    Sistemas Envolvidos

    • Protheus (módulo de Ponto Eletrônico): Módulo responsável pela gestão da assiduidade e marcações/apontamentos de horários de trabalho do funcionário, dentre outros cadastros pertinentes aos colaboradores.

    • Quírons - NG

    Integração

    O objetivo desta integração é permitir que o RH ou área responsável pelo Gestão de Pessoal do Protheus, receba os dados do Controle de Abono de marcações de ponto dos funcionários de outros sistemas especializados, reduzindo assim o trabalho de inclusão/alteração/exclusão manual dessas informações dentro do sistema;

    • Benefícios
      • Não terá um investimento alto de tempo para o cadastramento, pois os dados já serão enviados, editados ou excluídos através da integração a cada requisição do sistema especialista através da API de Abono.
      • A informação será atualizada de forma automática, facilitando que conferência e confiabilidade dos dados recebidos.
    • Arquitetura (Tecnologia)

    Toda integração entre o Protheus e o Sistema é feita por intermédio de comunicação direta com os Web Services(que são fixos) REST(Representation State Transfer) utilizando o formato JSON(JavaScript  Object Notation) de serialização de dados, onde através da ativação do serviço do REST do Protheus esteja disponível para utilizar o serviço.

    Escopo

    Por intermédio desta integração será disponibilizada a seguinte funcionalidade:

    • Manutenção de Lançamentos de Pré-Abono do funcionário no módulo SIGAPON;

    Fora do escopo

    • Automatização de consultas de Abono,
    • Importação de base cadastral - dados do Funcionário,
    • Informações do Abono que não se enquadram dentro da tabela de Abono


    Pré-requisitos instalação/implantação/utilização

    • Versões mínimas do Protheus: 12.1.23
    • Possuir acesso à Internet, caso o sistema que venha a utilizar a integração com a aplicação Protheus.
    • Estrutura de rede estável, para que haja tráfego de dados sem interrupção.
    • Protheus devidamente configurado e serviço Rest habilitado em seu server.


    Instalação/Atualização

    Este tópico tem por objetivo orientar a instalação da integração, visando o seu funcionamento completo.

    Instalação de produtos ou ferramentas necessárias podem referenciar outros documentos existentes, desde que estejam disponíveis no repositório de documentação da TOTVS ou sejam enviados junto com o documento da integração em si.

    As informações mínimas necessárias para este tópico são:

    Ativação/Desativação da integração

    Por padrão esta integração estará em repositório, porém demanda realizar a devida configuração conforme abaixo:

    Controle de Ambiente

    Exige que os seguintes pontos sejam revisados:

    • Protheus com sua arquitetura devidamente estruturada.
    • Módulo de Ponto Eletrônico (SIGAPON) com suas entidades base, devidamente populadas por dados que no momento da integração serão utilizados na criação do registro de abono. (Para melhor compreensão, analise o cadastro disponível dentro do sistema e verifique os campos que possuem consultas em outras tabelas se as mesmas estão com os seus dados devidamente cadastrados).

    Controle de Versão

    O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

    Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das marcas e alinhamento com as diretivas definidas pelo Comitê de Integração TOTVS.

    Suporte

    O suporte aos recursos da Integração será de responsabilidade da linha Protheus, onde será analisada pela equipe de suporte da Totvs.

    Fluxo das Informações

    Esta integração traz a funcionalidade exclusivamente à área de Ponto Eletrônico, no processo de cadastramento (inclusão/alteração/exclusão) de abonos de marcações de horário de ponto.

    Cadastro

    Esta integração contempla apenas o cadastramento(inclusão/alteração/exclusão) do Abono dentro do módulo SIGAPON.

    Processos

    O Sistema requisitante enviará as informações via json para a interface de integração, desta forma serão atualizados os dados de abono de marcações dentro do cadastro de pré abono no Protheus, caso tenha êxito na geração do registro, será retornada a mesma estrutura json recebida, acompanhada de uma nova tag chamada id, que será uma chave única composta de informações da entidade dentro do sistema.  Desta forma será confirmada sua gravação, caso contrário enviará as informações de inconsistências que serão citadas nos próximos tópicos.


    Limitações / Restrições Gerais

    • Com o objetivo de manter a estrutura e a agilidade da estrutura Rest, o Web Service Rest receberá o registro individual de cada registro de Abono.


    Como realizar a chamada da API REST

    Para realizar a integração com o parceiro TOTVS são necessárias as informações básicas de consulta para retorno do funcionário desejado.

    • Preenchimento do EndPoint da API PONA350API;
    • Utilizar a chamada do método Post, Put e Delete e do Serviço AllowanceControl;
    • Preenchimento dos parâmetros obrigatórios da API.


    Parâmetros de Entrada POST:

    Parâmetro

    Valor de Exemplo

    Obrigatório

    Tipo

    Valor Default

    Descrição
    authorization  usuario:senha Sim

    header


    autenticação é requerida para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
    content {
    "companyId":"T1",
    "branchId": "D MG 01 ",
    "employeeId":"T1|D MG 01 |160001",
    "code": "T1|D MG |114",
    "startDate": "2020-06-02T10:10:10",
    "endDate": "2020-06-10T10:10:10",
    "startTime": "10:10",
    "endTime": "19:10"
    }
    sim body

    Estrutura json com informações do abono de marcações do funcionário:

    Dados de preparação de ambiente:

    • companyId: Grupo de empresa
    • branchId: Empresa+Unidade de negócio+Filial

    Dados de Abono:

    • employeeId: Informação pertinente ao funcionário.
    • startDate: Data do Início do abono.
    • endDate: Data do Final do abono.
    • startTime: Hora do Início do abono.
    • endTime: Hora do Final do abono.
    • code: Tipo de Abono registrado.

    Parâmetros e Chamada do Método:

    Para a realização de testes foi utilizado a ferramenta POSTMAN e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

    {protocolo}://{host}/{api}/rh/v1/allowanceControl


    Dados utilizados da API

    Por ser uma estrutura única para todas as linhas, cada linha utilizará os campos pertinentes aos seus ambientes.

    Propriedade API REST CAMPO PROTHEUS DESCRIÇÃO Formato
    companyId
    Informações de acesso ao sistema, campo contém informação do grupo de empresa "T1"
    branchId RF0_FILIAL Informações de acesso ao sistema, campo compõe Empresa+Unidade de Negócio+ Filial "D MG 01 "
    employeeId RF0_MAT chave do Funcionário "T1|D MG 01 |000001""
    startDate RF0_DTPREI Data inicial do abono "2020-01-01T18:25:43"
    endDate RF0_DTPREF Data final do abono "2020-01-01T18:25:43"
    startTime RF0_HORINI hora inicial do abono "10:00"
    endTime RF0_HORFIM hora final do abono "15:00"
    code

    P6_CODIGO

    chave do tipo de abono "T1| D MG   | 107"

    Situações Tratadas

    O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros.
    Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.


    Mensagens Validação

    Erro

    Mensagem

    Solução

    API RESPONSE
    201 Created. Registro incluído com sucesso.
    "companyId":"T1",
    "branchId": "D MG 01 ",
    "employeeId":"T1|D MG 01 |160001",
    "code": "T1|D MG |114",
    "startDate": "2020-06-02T10:10:10",
    "endDate": "2020-06-10T10:10:10",
    "startTime": "10:10",
    "endTime": "19:10",
    "id": "T1;D MG 01 ;T1|D MG 01 |160001;2020-06-03T13:00:00.000Z;10:10;T1|D MG|107"
    

    400

    Erro no momento da listagem do registro.

    Verificar se as propriedade json startDate está preenchida e com dados válidos no pacote enviado .

    {
        "code": 400,
        "detailedMessage": "Verifique o conteúdo da TAG (startDate) pois a data não está no formato correto: 'YYYY-MM-DDTHH:MM:SS'\r\n",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    500

    Erro no acesso ao Endpoint.

    É necessário avaliar se o servidor está funcionando corretamente.
    {
        "code": 500,
        "detailedMessage": "Ocorreu uma falha no retorno da informação.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": Descrição do erro.
    }


    OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.


    Parâmetros de Entrada PUT:

    Parâmetro

    Valor de Exemplo

    Obrigatório

    Tipo

    Valor Default

    Descrição
    authorization  usuario:senha Sim

    header


    autenticação é importante para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
    allowanceId

    T1;D MG 01 ;T1|D MG 01 |160001;2020-06-03T13:00:00.000Z;10:10;T1|D MG|107

    Sim request

    Composição da string a ser enviada, deve ser ser composta por "GRUPO DE EMPRESA;FILIAL;CHAVEFUNCIONARIO;DATADEINÍCIO;HORADEINICIO;CHAVE TIPODEABONO".

    content layout json sim body

    Estrutura json com informações do abono de marcação de ponto:

    Dados de preparação de ambiente:

    • companyId: Grupo de empresa
    • branchId: Empresa+Unidade de negócio+Filial

    Dados de solicitação de abono:

    • employeeId: Informação pertinente ao funcionário.
    • startDate: Data inicial do abono.
    • endDate: Data final do abono.
    • startTime: Horário do Início do abono.
    • endTime: Horário do final do abono.
    • code: Tipo de abono registrado.

    Parâmetros e Chamada do Método:

    Para a realização de testes foi utilizado a ferramenta POSTMAN e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

    {protocolo}://{host}/{api}/rh/v1/allowanceControl{allowanceId}


    Dados utilizados da API

    Por ser uma estrutura única para todas as linhas, cada linha utilizará os campos pertinentes aos seus ambientes.

    Propriedade API REST CAMPO PROTHEUS DESCRIÇÃO Formato
    companyId
    Informações de acesso ao sistema, campo contém informação do grupo de empresa "T1"
    branchId
    Informações de acesso ao sistema, campo compõe Empresa+Unidade de Negócio+ Filial " D MG 01 "
    employeeId RF0_MAT chave do Funcionário. "T1|D MG 01 |000001"
    startDate RF0_DTPREI Data de Início do abono "2020-01-01T18:25:43"
    endDate RF0_DTPREF Data do Final do abono "2020-01-01T18:25:43"
    startTime RF0_HORINI Hora inicial do abono "10:00"
    endTime RF0_HORFIM Hora final do abono "15:00"
    code P6_CODIGO chave do tipo de abono "T1|D MG   |107"

    Situações Tratadas

    O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros.
    Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.


    Mensagens Validação

    Erro

    Mensagem

    Solução

    API RESPONSE
    200 Atualizado com sucesso. Registro alterado com sucesso.
    "companyId":"T1",
    "branchId": "D MG 01 ",
    "employeeId":"T1|D MG 01 |160001",
    "code": "T1|D MG |114",
    "startDate": "2020-06-02T10:10:10",
    "endDate": "2020-06-10T10:10:10",
    "startTime": "10:10",
    "endTime": "19:10",
    "id": "T1;D MG 01 ;T1|D MG 01 |160001;2020-06-03T13:00:00.000Z;10:10;T1|D MG|107"

    400

    Erro no momento da listagem do registro.

    Verificar se as propriedade json allowanceId está preenchida e com dados válidos no pacote enviado .

    {
        "code": 400,
        "detailedMessage": "Informação allowanceId ausente ou inválida.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    500

    Erro no acesso ao Endpoint.

    É necessário avaliar se o servidor está funcionando corretamente.
    {
        "code": 500,
        "detailedMessage": "Ocorreu uma falha no retorno da informação.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": Descrição do erro.
    }


    OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.




    Parâmetros de Entrada PUT:

    Parâmetro

    Valor de Exemplo

    Obrigatório

    Tipo

    Valor Default

    Descrição
    authorization  usuario:senha Sim

    header


    autenticação é importante para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
    allowanceId

    T1;D MG 01 ;T1|D MG 01 |160001;2020-06-03T13:00:00.000Z;10:10;T1|D MG|107

    Sim request

    Composição da string a ser enviada, deve ser ser composta por "GRUPO DE EMPRESA;FILIAL;CHAVEFUNCIONARIO;DATADEINÍCIO;HORADEINICIO;CHAVE TIPODEABONO".

    content layout json sim body

    Estrutura json com informações do abono de marcação de ponto:

    Dados de preparação de ambiente:

    • companyId: Grupo de empresa
    • branchId: Empresa+Unidade de negócio+Filial

    Dados de solicitação de abono:

    • employeeId: Informação pertinente ao funcionário.
    • startDate: Data inicial do abono.
    • endDate: Data final do abono.
    • startTime: Horário do Início do abono.
    • endTime: Horário do final do abono.
    • code: Tipo de abono registrado.

    Parâmetros e Chamada do Método:

    Para a realização de testes foi utilizado a ferramenta POSTMAN e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

    {protocolo}://{host}/{api}/rh/v1/allowanceControl{allowanceId}


    Dados utilizados da API

    Por ser uma estrutura única para todas as linhas, cada linha utilizará os campos pertinentes aos seus ambientes.

    Propriedade API REST CAMPO PROTHEUS DESCRIÇÃO Formato
    companyId
    Informações de acesso ao sistema, campo contém informação do grupo de empresa "T1"
    branchId
    Informações de acesso ao sistema, campo compõe Empresa+Unidade de Negócio+ Filial " D MG 01 "
    employeeId RF0_MAT chave do Funcionário. "T1|D MG 01 |000001"
    startDate RF0_DTPREI Data de Início do abono "2020-01-01T18:25:43"
    endDate RF0_DTPREF Data do Final do abono "2020-01-01T18:25:43"
    startTime RF0_HORINI Hora inicial do abono "10:00"
    endTime RF0_HORFIM Hora final do abono "15:00"
    code P6_CODIGO chave do tipo de abono "T1|D MG   |107"

    Situações Tratadas

    O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros.
    Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.


    Mensagens Validação

    Erro

    Mensagem

    Solução

    API RESPONSE
    200 Atualizado com sucesso. Registro alterado com sucesso.
    "companyId":"T1",
    "branchId": "D MG 01 ",
    "employeeId":"T1|D MG 01 |160001",
    "code": "T1|D MG |114",
    "startDate": "2020-06-02T10:10:10",
    "endDate": "2020-06-10T10:10:10",
    "startTime": "10:10",
    "endTime": "19:10",
    "id": "T1;D MG 01 ;T1|D MG 01 |160001;2020-06-03T13:00:00.000Z;10:10;T1|D MG|107"

    400

    Erro no momento da listagem do registro.

    Verificar se as propriedade json allowanceId está preenchida e com dados válidos no pacote enviado .

    {
        "code": 400,
        "detailedMessage": "Informação allowanceId ausente ou inválida.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    500

    Erro no acesso ao Endpoint.

    É necessário avaliar se o servidor está funcionando corretamente.
    {
        "code": 500,
        "detailedMessage": "Ocorreu uma falha no retorno da informação.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": Descrição do erro.
    }




    OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.

    Parâmetros de Entrada DELETE:

    Parâmetro

    Valor de Exemplo

    Obrigatório

    Tipo

    Valor Default

    Descrição
    authorization  usuario:senha Sim

    header


    autenticação é importante para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
    allowanceId

    "T1;D MG 01 ;T1|D MG 01 |160001;2020-06-03T13:00:00.000Z;10:10;T1|D MG|107"

    Sim query

    Composição da string a ser enviada, deve ser ser composta por "GRUPO DE EMPRESA;FILIAL;CHAVEFUNCIONARIO;DATADEINÍCIO;HORADEINICIO;CHAVE TIPODEABONO".

    Parâmetros e Chamada do Método:

    Para a realização de testes foi utilizado a ferramenta POSTMAN e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

    {protocolo}://{host}/{api}/rh/v1/allowanceControl{allowanceId}

    Situações Tratadas

    O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros.
    Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.


    Mensagens Validação

    Erro

    Mensagem

    Solução

    API RESPONSE
    200 Atualizado com sucesso. Registro foi deletado com sucesso.
    {
        "code": "200",
        "description": "Opera��o realizada com sucesso!"
    }

    400

    Erro no momento da listagem do registro.

    Verificar se a propriedade json allowanceId está preenchida e com dados válidos no pacote enviado .

    {
        "code": 400,
        "detailedMessage": "Informação allowanceId ausente ou inválida.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    500

    Erro no acesso ao Endpoint.

    É necessário avaliar se o servidor está funcionando corretamente.
    {
        "code": 500,
        "detailedMessage": "Ocorreu uma falha no retorno da informação.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": Descrição do erro.
    }


    OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.

    Checklist de suporte da aplicação

    Itens a serem verificados durante o atendimento:

    • Verificar se os pré-requisitos foram atendidos para a chamada da API;
    • Verificar se na chamada da API o EndPoint, o nome do serviço e todos os campos obrigatórios foram informados;
    • Verificar se o retorno da API apresenta algum erro tratado (códigos e mensagens de erro citados neste documento) e consultar a solução na mesma tabela que descreve o erro;
    • Em caso de erro não tratado, verificar se possui alguma informação de banco de dados, conexão com o servidor ou algo que possa identificar a origem do problema.



    Solicitação de Treinamento - trainingNecessity - INTEGRAÇÃO GPEA923API


    Sistemas Envolvidos

    • Protheus (módulo Treinamento): Módulo responsável pela gestão de cursos e treinamentos realizados pelos colaboradores.

    • Quírons - NG

    Integração

    O objetivo desta integração é permitir que o RH ou área responsável pela Gestão de Treinamentos dos Colaboradores no Protheus, receba os dados do Controle de Solicitações de Treinamento dos funcionários de outros sistemas especializados, reduzindo assim o trabalho de inclusão/alteração/exclusão manual dessas informações dentro do sistema;

    • Benefícios
      • Não terá um investimento alto de tempo para o cadastramento, pois os dados já serão enviados, editados ou excluídos através da integração a cada requisição do sistema especialista através da API de Solicitação de Treinamento.
      • A informação será atualizada de forma automática, facilitando que conferência e confiabilidade dos dados recebidos.
    • Arquitetura (Tecnologia)

    Toda integração entre o Protheus e o Sistema é feita por intermédio de comunicação direta com os Web Services(que são fixos) REST(Representation State Transfer) utilizando o formato JSON(JavaScript  Object Notation) de serialização de dados, onde através da ativação do serviço do REST do Protheus esteja disponível para utilizar o serviço.

    Escopo

    Por intermédio desta integração será disponibilizada a seguinte funcionalidade:

    • Manutenção de solicitações de necessidade de treinamento do funcionário no módulo SIGATRM;

    Fora do escopo

    • Automatização de consultas de solicitação de treinamento,
    • Importação de base cadastral - dados do Funcionário,
    • Informações da solicitações de treinamento que não se enquadram dentro da tabela de solicitação de treinamento


    Pré-requisitos instalação/implantação/utilização

    • Versões mínimas do Protheus: 12.1.23
    • Possuir acesso à Internet, caso o sistema que venha a utilizar a integração com a aplicação Protheus.
    • Estrutura de rede estável, para que haja tráfego de dados sem interrupção.
    • Protheus devidamente configurado e serviço Rest habilitado em seu server.


    Instalação/Atualização

    Este tópico tem por objetivo orientar a instalação da integração, visando o seu funcionamento completo.

    Instalação de produtos ou ferramentas necessárias podem referenciar outros documentos existentes, desde que estejam disponíveis no repositório de documentação da TOTVS ou sejam enviados junto com o documento da integração em si.

    As informações mínimas necessárias para este tópico são:

    Ativação/Desativação da integração

    Por padrão esta integração estará em repositório, porém demanda realizar a devida configuração conforme abaixo:

    Controle de Ambiente

    Exige que os seguintes pontos sejam revisados:

    • Protheus com sua arquitetura devidamente estruturada.
    • Módulo de Treinamento (SIGATRM) com suas entidades base, devidamente populadas por dados que no momento da integração serão utilizados na criação do registro de solicitação de necessidade de treinamento. (Para melhor compreensão, analise o cadastro disponível dentro do sistema e verifique os campos que possuem consultas em outras tabelas se as mesmas estão com os seus dados devidamente cadastrados).

    Controle de Versão

    O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

    Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das marcas e alinhamento com as diretivas definidas pelo Comitê de Integração TOTVS.

    Suporte

    O suporte aos recursos da Integração será de responsabilidade da linha Protheus, onde será analisada pela equipe de suporte da Totvs.

    Fluxo das Informações

    Esta integração traz a funcionalidade exclusivamente à área de Treinamento, no processo de cadastramento (inclusão/alteração/exclusão) de solicitação de Necessidade de Treinamento.

    Cadastro

    Esta integração contempla apenas o cadastramento(inclusão/alteração/exclusão) da solicitação de necessidade de treinamento dentro do módulo SIGATRM.

    Processos

    O Sistema requisitante enviará as informações via json para a interface de integração, desta forma será gerado um novo registro na tabela de solicitações de necessidade de treinamentos no Protheus, caso tenha êxito na geração do registro, será retornada a mesma estrutura de json recebida, acompanhada de uma nova tag chamada id, que será uma chave única composta de informações da entidade dentro do sistema.  Desta forma será confirmada sua gravação, caso contrário enviará as informações de inconsistências que serão citadas nos próximos tópicos.


    Limitações / Restrições Gerais

    • Com o objetivo de manter a estrutura e a agilidade da estrutura Rest, o Web Service Rest receberá o registro individual de cada solicitação de treinamento.


    Como realizar a chamada da API REST

    Para realizar a integração com o parceiro TOTVS são necessárias as informações básicas de consulta para retorno do funcionário desejado.

    • Preenchimento do EndPoint da API TRMA010API;
    • Utilizar a chamada do método Post, Put e Delete e do Serviço trainingNecessity;
    • Preenchimento dos parâmetros obrigatórios da API.

    Parâmetros de Entrada POST:

    Parâmetro

    Valor de Exemplo

    Obrigatório

    Tipo

    Valor Default

    Descrição
    authorization  usuario:senha Sim

    header


    autenticação é requerida para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
    content

    {
    "companyId""T1",
    "branchId""D MG 01 ",
    "employeeId""T1|D MG 01 |160001",
    "trainingNecessityCode""T1|D MG    |0003"
    }

    Sim body

    Estrutura json com informações de necessidade de treinamento:

    Propriedades Obrigatórias:

    Dados de preparação de ambiente:

    • companyId: Grupo de empresa
    • branchId: Empresa+Unidade de negócio+Filial

    Dados de solicitação de treinamento:

    • employeeId: Informação pertinente ao funcionário.
    • trainingNecessityCode: Tipo de treinamento registrado.

    Parâmetros e Chamada do Método:

    Para a realização de testes foi utilizado a ferramenta POSTMAN e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

    {protocolo}://{host}/{api}/rh/v1/trainingnecessity



    Dados utilizados da API

    Por ser uma estrutura única para todas as linhas, cada linha utilizará os campos pertinentes aos seus ambientes.

    Propriedade API REST CAMPO PROTHEUS DESCRIÇÃO Formato
    companyId
    Informações de acesso ao sistema, campo contém informação do grupo de empresa "T1"
    branchId RA3_FILIAL Informações de acesso ao sistema, campo compõe Empresa+Unidade de Negócio+ Filial "D MG 01 "
    employeeId Empresa|RA_FILIAL|MAT Chave do funcionário "T1|D MG 01 |000001"

    trainingnecessidadecode

    Empresa|RA2_FILIAL|RA2_CURSO

    Chave do curso T1|D MG   |001"

    Situações Tratadas

    O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros.
    Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.


    Mensagens Validação

    Erro

    Mensagem

    Solução

    API RESPONSE
    201 Registro criado. Registro incluído com sucesso.
    {
        "companyId": "T1",
        "branchId": "D MG 01 ",
        "trainingNecessityCode": "T1|D MG    |0001",
        "employeeId": "T1|D MG 01 |160001",
        "id": "T1;D MG 01 ;T1|D MG 01 |160001;T1|D MG    |0001"
    }
    400 Erro na validação do recebimento da mensagem. Verificar se as propriedade json trainingNecessityCode
    está preenchida e com dados válidos no pacote enviado ..
    {
        "code": 400,
        "detailedMessage": "Erro na validacao do recebimento da mensagem",
        "helpUrl": "https://tdn.totvs.com/x/BJuMHw",
        "message": "Verifique o conteudo da TAG (trainingNecessityCode) pois nao foi possivel encontrar esta informacao no Protheus.\r\n"
    }
    500

    Ocorreu uma falha no retorno da informação.

    É necessário avaliar se o servidor está funcionando corretamente.
    {
       "errorCode": 500,
       "errorMessage": "Ocorreu uma falha no retorno da informação."
    }


    OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.


    Parâmetros de Entrada PUT:

    Parâmetro

    Valor de Exemplo

    Obrigatório

    Tipo

    Valor Default

    Descrição
    authorization  usuario:senha Sim

    header


    autenticação é importante para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
    trainingNecessityId

    T1;D MG 01 ;T1|D MG 01 |160001;T1|D MG |0004

    Sim request

    Composição da string a ser enviada, deve ser ser composta por "GRUPODEEMPRESA|RA3_FILIAL|CHAVEDOFUNCIOARIO|CHAVEDOCURSO".

    content layout json sim body

    Estrutura json com informações de necessidade de treinamento:

    Propriedades Obrigatórias:

    Dados de preparação de ambiente:

    • companyId: Grupo de empresa
    • branchId: Empresa+Unidade de negócio+Filial

    Dados de solicitação de treinamento:

    • employeeId: Informação pertinente ao funcionário.
    • trainingNecessityCode: Tipo de treinamento registrado.

    Parâmetros e Chamada do Método:

    Para a realização de testes foi utilizado a ferramenta POSTMAN e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

    {protocolo}://{host}/{api}/rh/v1/trainingNecessity{trainingNecessityId}



    Dados utilizados da API

    Por ser uma estrutura única para todas as linhas, cada linha utilizará os campos pertinentes aos seus ambientes.

    Propriedade API REST CAMPO PROTHEUS DESCRIÇÃO Formato
    companyId
    Informações de acesso ao sistema, campo contém informação do grupo de empresa "T1"
    branchId RA3_FILIAL Informações de acesso ao sistema, campo compõe Empresa+Unidade de Negócio+ Filial "D MG 01"
    employeeId RA3_MAT Chave do Funcionário. "T1|D MG 01 |000001"

    trainingNecessityCode

    RA2_CURSO Chave do Curso "T1|D MG |001"

    Situações Tratadas

    O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros.
    Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.


    Mensagens Validação

    Erro

    Mensagem

    Solução

    API RESPONSE
    200 Atualizado com sucesso. Registro alterado com sucesso.
    {
        "companyId": "T1",
        "branchId": "D MG 01 ",
        "trainingNecessityCode": "T1|D MG    |0001",
        "employeeId": "T1|D MG 01 |160001",
        "id": "T1;D MG 01 ;T1|D MG 01 |160001;T1|D MG    |0001"
    }

    400

    Erro na validação do recebimento da mensagem.

    Verificar se as propriedade json trainingNecessityId está preenchida e com dados válidos no pacote enviado.

    1. Dados de Empresa e Filial,
    2. Dados de Filial e Matrícula,
    3. Código do curso;
    {
        "code": 400,
        "detailedMessage": "Informação trainingNecessityId ausente ou inválida.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    500

    Ocorreu uma falha no retorno da informação.

    É necessário avaliar se o servidor está funcionando corretamente.
    {
       "errorCode": 500,
       "errorMessage": "Ocorreu uma falha no retorno da informação."
    }


    OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.



    Parâmetros de Entrada DELETE:

    Parâmetro

    Valor de Exemplo

    Obrigatório

    Tipo

    Valor Default

    Descrição
    authorization  usuario:senha Sim

    header


    autenticação é importante para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
    trainingNecessityId

    T1;D MG 01 ;T1|D MG 01 |160001;T1|D MG |0003

    Sim query

    Composição da string a ser enviada, deve ser ser composta por "GRUPODEEMPRESA|RA3_FILIAL|CHAVEDOFUNCIOARIO|CHAVEDOCURSO".

    Parâmetros e Chamada do Método:

    Para a realização de testes foi utilizado a ferramenta POSTMAN e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

    {protocolo}://{host}/{api}/rh/v1/trainingNecessity{trainingNecessityid}

    Situações Tratadas

    O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros.
    Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.


    Mensagens Validação

    Erro

    Mensagem

    Solução

    API RESPONSE
    200 Atualizado com sucesso. Registro foi deletado com sucesso.
    {
        "code": "200",
        "description": "Opera��o realizada com sucesso!"
    }

    400

    Erro na validação do recebimento da mensagem.

    Verificar se as propriedade json trainingNecessityId está preenchida e com dados válidos no pacote enviado.

    1. Dados de Empresa e Filial,
    2. Dados de Filial e Matrícula,
    3. Código do Curso.
    {
        "code": 400,
        "detailedMessage": "Informação trainingNecessityId ausente ou inválida.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    500

    Erro no acesso ao Endpoint.

    É necessário avaliar se o servidor está funcionando corretamente.
    {
       "errorCode": 500,
       "errorMessage": "Ocorreu uma falha no retorno da informação."
    }


    OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.

    Checklist de suporte da aplicação

    Itens a serem verificados durante o atendimento:

    • Verificar se os pré-requisitos foram atendidos para a chamada da API;

    • Verificar se na chamada da API o EndPoint, o nome do serviço e todos os campos obrigatórios foram informados;
    • Verificar se o retorno da API apresenta algum erro tratado (códigos e mensagens de erro citados neste documento) e consultar a solução na mesma tabela que descreve o erro;
    • Em caso de erro não tratado, verificar se possui alguma informação de banco de dados, conexão com o servidor ou algo que possa identificar a origem do problema.



    Controle de Afastamentos/Ausências - leaveOfAbsenceControl - INTEGRAÇÃO GPEA240API - 


    Sistemas Envolvidos

    • Protheus (módulo  Gestão de Pessoal): Módulo responsável pela gestão dos dados dos funcionários, folha de pagamento e dentre outros cadastros pertinentes aos colaboradores.

    • Quírons - NG

    Integração

    O objetivo desta integração é permitir que o RH ou área responsável pelo Gestão de Pessoal do Protheus, receba os dados do Controle de Afastamentos/Ausências dos funcionários de outros sistemas especializados, reduzindo assim o trabalho de inclusão/alteração/exclusão manual dessas informações dentro do sistema;

    • Benefícios
      • Não terá um investimento alto de tempo para o cadastramento, pois os dados já serão enviados, editados ou excluídos através da integração a cada requisição do sistema especialista através da API de Afastamentos/Ausências.
      • A informação será atualizada de forma automática, facilitando que conferência e confiabilidade dos dados recebidos.
    • Arquitetura (Tecnologia)

    Toda integração entre o Protheus e o Sistema é feita por intermédio de comunicação direta com os Web Services(que são fixos) REST(Representation State Transfer) utilizando o formato JSON(JavaScript  Object Notation) de serialização de dados, onde através da ativação do serviço do REST do Protheus esteja disponível para utilizar o serviço.

    Escopo

    Por intermédio desta integração será disponibilizada a seguinte funcionalidade:

    • Manutenção do controle de afastamentos/ausências do funcionário no módulo SIGAGPE;

    Fora do escopo

    • Automatização de consultas de controle de afastamentos,
    • Importação de base cadastral - dados do Funcionário,
    • Informações do controle de afastamentos que não se enquadram dentro da tabela de controle de afastamentos.


    Pré-requisitos instalação/implantação/utilização

    • Versões mínimas do Protheus: 12.1.23
    • Possuir acesso à Internet, caso o sistema que venha a utilizar a integração com a aplicação Protheus.
    • Estrutura de rede estável, para que haja tráfego de dados sem interrupção.
    • Protheus devidamente configurado e serviço Rest habilitado em seu server.


    Instalação/Atualização

    Este tópico tem por objetivo orientar a instalação da integração, visando o seu funcionamento completo.

    Instalação de produtos ou ferramentas necessárias podem referenciar outros documentos existentes, desde que estejam disponíveis no repositório de documentação da TOTVS ou sejam enviados junto com o documento da integração em si.

    As informações mínimas necessárias para este tópico são:

    Ativação/Desativação da integração

    Por padrão esta integração estará em repositório, porém demanda realizar a devida configuração conforme abaixo:

    Controle de Ambiente

    Exige que os seguintes pontos sejam revisados:

    • Protheus com sua arquitetura devidamente estruturada.
    • Módulo de Gestão de Pessoal (SIGAGPE) com suas entidades base, devidamente populadas por dados que no momento da integração serão utilizados na criação do registro de afastamento/ausências. (Para melhor compreensão, analise o cadastro disponível dentro do sistema e verifique os campos que possuem consultas em outras tabelas se as mesmas estão com os seus dados devidamente cadastrados).

    Controle de Versão

    O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

    Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das marcas e alinhamento com as diretivas definidas pelo Comitê de Integração TOTVS.

    Suporte

    O suporte aos recursos da Integração será de responsabilidade da linha Protheus, onde será analisada pela equipe de suporte da Totvs.

    Fluxo das Informações

    Esta integração traz a funcionalidade exclusivamente à área de Gestão de Pessoal, no processo de cadastramento (inclusão/alteração/exclusão) de Afastamento/Ausências.

    Cadastro

    Esta integração contempla apenas o cadastramento(inclusão/alteração/exclusão) do cadastro de Afastamento/Ausências dentro do módulo SIGAGPE.

    Processos

    O Sistema requisitante enviará as informações via json para a interface de integração, desta forma será gerado um novo registro na tabela de Afastamentos/Ausências no Protheus, caso tenha êxito na geração do registro, será retornada a mesma estrutura de json recebida, acompanhada de uma nova tag chamada id, acompanhada de uma nova tag chamada id, que será uma chave única composta de informações da entidade dentro do sistema.  Desta forma será confirmada sua gravação, caso contrário enviará as informações de inconsistências que serão citadas nos próximos tópicos.


    Limitações / Restrições Gerais

    • Com o objetivo de manter a estrutura e a agilidade da estrutura Rest, o Web Service Rest receberá o registro individual de cada afastamento.


    Como realizar a chamada da API REST

    Para realizar a integração com o parceiro TOTVS são necessárias as informações básicas de consulta para retorno do funcionário desejado.

    • Preenchimento do EndPoint da API GPEA240API;
    • Utilizar a chamada do método Post, Put e Delete e do Serviço leaveOfAbsenceControl;
    • Preenchimento dos parâmetros obrigatórios da API.

    Parâmetros de Entrada POST:

    Parâmetro Valor de Exemplo Obrigatório Tipo Valor Default Descrição
    authorization  usuario:senha Sim header
    autenticação é importante para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
    content request da api Sim body
    Estrutura json com informações de cadastro do currículo:Propriedades Obrigatórias:Dados de preparação de ambiente:
    • companyId: Grupo de empresa
    • branchId: Empresa+Unidade de negócio+Filial
    Dados de controle de afastamentos:
    • employeeId: Informação pertinente ao funcionário.
    • startDate: Data inicial do afastamento.
    • endDate: Data final do afastamento.
    • leaveOfAbsenceCode: Código do tipo de afastamento.
    • internationalDiseaseClassification: Código internacional de doenças.
    • classEntityRegistrationCode: Número do registro do profissional
    • doctorName: Nome do profissional.
    • classEntityState: Estado do profissional.
    • classEntity: Tipo de registro do profissional.
    • sequence: Chave do afastamento anterior que será continuado.

    Parâmetros e Chamada do Método:

    Para a realização de testes foi utilizado a ferramenta POSTMAN e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

    {protocolo}://{host}/{api}/rh/v1/leaveOfAbsenceControl


    Dados utilizados da API

    Por ser uma estrutura única para todos os produtos, há dados que existem em um produto (RM) e não existe no Protheus, desta forma cada produto utilizará os campos pertinentes aos seus ambientes.

    Propriedade API REST

    CAMPO PROTHEUS

    DESCRIÇÃO

    Formato

    companyId
    Informações de acesso ao sistema, campo contém informação do grupo de empresa
    branchId R8_FILIAL Informações de acesso ao sistema, campo compõe Empresa+Unidade de Negócio+ Filial "D MG 01 "
    employeeId R8_MAT Chave do Funcionário

    "T1|D MG 01 |160001"

    startDate R8_DATAINI Data inicial do afastamento "20200101"
    endDate R8_DATAFIM Data final do afastamento "20200101"

    leaveOfAbsenceCode

    R8_TIPOAFA

    Chave do tipo de afastamento

    "T1|D MG    |005"

    internationalDiseaseClassification

    R8_CID Código internacional de doenças.

    "A07.8"

    classEntityRegistrationCode

    R8_CRMMED Número do registro do profissional

    "123123"

    doctorName

    R8_NMMED Nome do profissional.

    "doctorName"

    classEntityState

    R8_UFCRM Estado do profissional. "MG"

    classEntity

    R8_IDEOC Tipo de registro do profissional. "2"
    sequence (opcional) R8_CONTAFA Apenas quando for continuação, deve ser informado o id do afastamento que será continuado e a API gravará a sequencia correta. "T1;D MG 01 ;T1|D MG 01 |160001;2019-12-30T10:00:00;00:00;2019-12-31T20:00:00;T1|D MG    |005"

    Situações Tratadas

    O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros.
    Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.


    Mensagens Validação

    Erro

    Mensagem

    Solução

    API RESPONSE
    201 Registro criado. Registro incluído com sucesso.
    {
        "branchId": "D MG 01 ",
        "startDate": "2020-06-05T10:10:10",
        "endDate": "2020-06-05T19:10:10",
        "employeeId": "T1|D MG 01 |160001",
        "leaveOfAbsenceCode": "T1|D MG    |005",
        "classEntityState": "SP",
        "companyId": "T1",
        "classEntityRegistrationCode": "123123",
        "doctorName": "doctorName Alves",
        "id": "T1;D MG 01 ;T1|D MG 01 |160001;2020-06-05T10:10:10;00:00;2020-06-05T19:10:10;T1|D MG    |005",
        "classEntity": "2",
        "internationalDiseaseClassification": "A07.8"
    }

    400

    Erro na validação do recebimento da mensagem.

    Verificar se as propriedades json companyId ou branchId estão preenchidas com conteúdo válido.

    {
        "code": 400,
        "detailedMessage": "De-Para de Empresa/Filial não encontrado na base.\r\n",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem. Verificar se o campo foi enviado no corpo da mensagem.
    {
        "code": 400,
        "detailedMessage": "Verifique se a TAG ( ) foi informada, pois ela é obrigatória para a manipulação deste processo.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem. Verificar se o campo foi enviado com conteúdo válido.
    {
        "code": 400,
        "detailedMessage": "Verifique o conteúdo do campo ( ) foi informada, pois ela é obrigatória para a manipulação deste processo.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem. Verificar se o campo foi enviado com conteúdo válido.
    {
        "code": 400,
        "detailedMessage": "Verifique o conteúdo do campo Tipo Orgão de Classe(classEntity) pois a informação está diferente do formato correto: 1 ou 2 ou 3",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem. Verificar se o campo foi enviado com conteúdo válido.
    {
        "code": 400,
        "detailedMessage": "Verifique o conteúdo do campo Inicio do Afastamento(startDate) pois está diferente do formado esperado: (yyyy-mm-ddThh:mm:ss).",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem. Verificar se o campo foi enviado com conteúdo válido.
    {
        "code": 400,
        "detailedMessage": "Verifique o conteúdo do campo Empresa + Filial(companyId + branchId) pois não foi possível encontrar esta informação no Protheus.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem. Verificar se o campo foi enviado com conteúdo válido.
    {
        "code": 400,
        "detailedMessage": "Verifique o conteúdo do campo ID do Funcionário(employeeId) pois não respeita a estrutura predefinida companyId | branchId | Matricula no ERP(Tabela SRA)",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem. Verifique se o funcionário existe no cadastro do Protheus(SRA).
    {
        "code": 400,
        "detailedMessage": "Verifique o conteúdo do campo ID do Funcionário(employeeId) pois não foi possível encontrar esta informação no Protheus.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem. Verificar se o campo foi enviado com conteúdo válido.
    {
        "code": 400,
        "detailedMessage": "Verifique o conteúdo do campo Tipo do Afastamento(leaveOfAbsenceCode) pois não respeita a estrutura predefinida companyId|branchId| Tipo do Afastamento no ERP(Tabela RCM)",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem. Verifique se o tipo de afastamento existe no cadastro do Protheus(RCM).
    {
        "code": 400,
        "detailedMessage": "Verifique o conteúdo do campo Tipo do Afastamento(leaveOfAbsenceCode) pois não foi possível encontrar esta informação no Protheus.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    500

    Ocorreu uma falha no retorno da informação.

    É necessário avaliar se o servidor está funcionando corretamente.
    {
       "errorCode": 500,
       "errorMessage": "Ocorreu uma falha no retorno da informação."
    }


    OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.


    Parâmetros de Entrada PUT:

    Parâmetro

    Valor de Exemplo

    Obrigatório

    Tipo

    Valor Default

    Descrição
    authorization  usuario:senha Sim

    header

    "" autenticação é importante para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
    leaveOfAbsenceId

    T1;D MG 01 ;T1|D MG 01 |160001;2020-06-01T10:10:10;00:00;2020-06-02T19:10:10;T1|D MG |005

    Sim request ""

    Composição da string a ser enviada, deve ser ser composta por "GRUPODEEMPRESA|R8_FILIAL|CHAVEFUNCIONARIO|DATAINICIAL|HORAINICIAL|DATAFINAL|CODIGOAFASTAMENTO".

    content layout json sim body ""

    Estrutura json com informações de cadastro do currículo:

    Propriedades Obrigatórias:

    Dados de preparação de ambiente:

    • companyId: Grupo de empresa
    • branchId: Empresa+Unidade de negócio+Filial

    Dados de controle de afastamentos:

    • employeeId: Informação pertinente ao funcionário.
    • startDate: Data inicial do afastamento.
    • endDate: Data final do afastamento.
    • leaveOfAbsenceCode: Código do tipo de afastamento.
    • internationalDiseaseClassification: Código internacional de doenças.
    • classEntityRegistrationCode: Número do registro do profissional
    • doctorName: Nome do profissional.
    • classEntityState: Estado do profissional.
    • classEntity: Tipo de registro do profissional.

    Parâmetros e Chamada do Método:

    Para a realização de testes foi utilizado a ferramenta POSTMAN e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

    {protocolo}://{host}/{api}/rh/v1/leaveOfAbsenceControl


    Dados utilizados da API

    Por ser uma estrutura única para todos os produtos, há dados que existem em um produto (RM) e não existe no Protheus, desta forma cada produto utilizará os campos pertinentes aos seus ambientes.

    Propriedade API REST

    CAMPO PROTHEUS

    DESCRIÇÃO

    Formato

    companyId
    Informações de acesso ao sistema, campo contém informação do grupo de empresa
    branchId RFX_FILIAL Informações de acesso ao sistema, campo compõe Empresa+Unidade de Negócio+ Filial
    employeeId R8_MAT Chave do Funcionário

    "T1|D MG 01 |160001"

    startDate R8_DATAINI Data inicial do afastamento "20200101"
    endDate R8_DATAFIM Data final do afastamento "20200101"

    leaveOfAbsenceCode

    R8_TIPOAFA

    Chave do tipo de afastamento

    "T1|D MG    |005"

    internationalDiseaseClassification

    R8_CID Código internacional de doenças.

    "A07.8"

    classEntityRegistrationCode

    R8_CRMMED Número do registro do profissional

    "123123"

    doctorName

    R8_NMMED Nome do profissional.

    "doctorName"

    classEntityState

    R8_UFCRM Estado do profissional. "MG"

    classEntity

    R8_IDEOC Tipo de registro do profissional. "2"
    sequence (opcional) R8_CONTAFA Apenas quando for continuação, deve ser informado o id do afastamento que será continuado e a API gravará a sequencia correta. "T1;D MG 01 ;T1|D MG 01 |160001;2019-12-30T10:00:00;00:00;2019-12-31T20:00:00;T1|D MG    |005"

    Situações Tratadas

    O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros.
    Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.


    Mensagens Validação

    Erro

    Mensagem

    Solução

    API RESPONSE
    200 Atualizado com sucesso. Registro alterado com sucesso.
    {
        "branchId": "D MG 01 ",
        "startDate": "2020-06-05T10:10:10",
        "endDate": "2020-06-05T19:10:10",
        "employeeId": "T1|D MG 01 |160001",
        "leaveOfAbsenceCode": "T1|D MG    |005",
        "classEntityState": "SP",
        "companyId": "T1",
        "classEntityRegistrationCode": "123123",
        "doctorName": "doctorName Alves",
        "id": "T1;D MG 01 ;T1|D MG 01 |160001;2020-06-05T10:10:10;00:00;2020-06-05T19:10:10;T1|D MG    |005",
        "classEntity": "2",
        "internationalDiseaseClassification": "A07.8"
    }

    400

    Erro na validação do recebimento da mensagem.

    Verificar se as propriedade json leaveOfAbsenceId está preenchida e com dados válidos no pacote enviado.

    1. Dados de Empresa e Filial,
    2. Dados de Filial e Matrícula,
    3. Formato da Data de Início,
    {
        "code": 400,
        "detailedMessage": "Informação leaveOfAbsenceId ausente ou inválida.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem. A chave recebida possui estrutura inválida.
    {
        "code": 400,
        "detailedMessage": "Chave do Afastamento(leaveOfAbsenceId) recebido(a) na URL da requisicao possui estrutura invalida. Estrutura esperada:  companyId;branchId;employeeId;startDate;startTime;endDate;leaveOfAbsenceCode",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem. Id do funcionário com estrutura inválida(employeeId).
    {
        "code": 400,
        "detailedMessage": "ID do Funcionario(employeeId) que compoe o(a) Chave do Afastamento(leaveOfAbsenceId) recebido(a) na URL da requisicao possui estrutura invalida. Estrutura esperada: companyId | branchId | Matricula no ERP(Tabela SRA)",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem. Id do afastamento (leaveOfAbsenceCode) com estrutura inválida.
    {
        "code": 400,
        "detailedMessage": "Tipo do Afastamento(leaveOfAbsenceCode) que compoe o(a) Chave do Afastamento(leaveOfAbsenceId) recebido(a) na URL da requisicao possui estrutura invalida. Estrutura esperada: companyId | branchId | Tipo do Afastamento no ERP(Tabela RCM)",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem. Empresa + Filial inválida.
    {
        "code": 400,
        "detailedMessage": "Empresa + Filial(COMPANYID + BRANCHID) que compoe o(a) Chave do Afastamento(leaveOfAbsenceId) recebido(a) na URL da requisicao nao corresponde a uma empresa/filial do Protheus.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem. Data inicio possui formato inválido.
    {
        "code": 400,
        "detailedMessage": "Inicio do Afastamento(startDate) que compoe o(a) Chave do Afastamento(leaveOfAbsenceId) recebido(a) na URL da requisicao possui estrutura invalida. Estrutura esperada: AAAAMMDD",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem. Data final possui formato inválido.
    {
        "code": 400,
        "detailedMessage": "Data Final do Afastamento(endDate) que compoe o(a) Chave do Afastamento(leaveOfAbsenceId) recebido(a) na URL da requisicao possui estrutura invalida. Estrutura esperada: AAAAMMDD",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem. Matrícula não existe no Protheus(SRA).
    {
        "code": 400,
        "detailedMessage": "ID do Funcionario(employeeId) que compoe o(a) Chave do Afastamento(leaveOfAbsenceId) recebido(a) na URL da requisicao nao corresponde a um funcionario valido no Protheus (Tabela SRA).",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem. Tipo de afastamento não existe no Protheus(RCM).
    {
        "code": 400,
        "detailedMessage": "Tipo do Afastamento(leaveOfAbsenceCode) que compoe o(a) Chave do Afastamento(leaveOfAbsenceId) recebido(a) na URL da requisicao nao corresponde a um tipo de afastamento valido no Protheus (Tabela RCM). ",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem. Chave não informada está em branco.
    {
        "code": 400,
        "detailedMessage": "Chave do Afastamento(leaveOfAbsenceId) que era esperado(a) na URL da requisicao esta ausente.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem. Afastamento referenciado não existe na (SR8)(informou dados incorretos).
    {
        "code": 400,
        "detailedMessage": "O afastamento que deseja alterar nao foi encontrado no Protheus(Tabela SR8), verifique.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    500

    Ocorreu uma falha no retorno da informação.

    É necessário avaliar se o servidor está funcionando corretamente.
    {
       "errorCode": 500,
       "errorMessage": "Ocorreu uma falha no retorno da informação."
    }


    OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.

    Parâmetros de Entrada DELETE:

    Parâmetro

    Valor de Exemplo

    Obrigatório

    Tipo

    Valor Default

    Descrição
    authorization  usuario:senha Sim

    header

    "" autenticação é importante para o funcionamento correto da API em casos de ambientes com autenticação Http Basic.
    leaveOfAbsenceId 

    T1;D MG 01 ;T1|D MG 01 |160001;2020-06-01T10:10:10;00:00;2020-06-02T19:10:10;T1|D MG |005

    Sim query ""

    Composição da string a ser enviada, deve ser ser composta por "GRUPODEEMPRESA|R8_FILIAL|CHAVEFUNCIONARIO|DATAINICIAL|HORAINICIAL|DATAFINAL|CODIGOAFASTAMENTO"

    Parâmetros e Chamada do Método:

    Para a realização de testes foi utilizado a ferramenta POSTMAN e após a configuração do server protheus a API Rest, a  requisição deverá ser semelhante a imagem abaixo:

    {protocolo}://{host}/{api}/rh/v1/leaveOfAbsenceControl

    Situações Tratadas

    O envio de dados inesperados nos parâmetros de entrada da API REST pode ocasionar alguns erros.
    Desta forma, foram criados alguns tratamentos de erros, listados abaixo, cada um com sua respectiva mensagem e solução.


    Mensagens Validação

    Erro

    Mensagem

    Solução

    API RESPONSE
    200 Registro foi deletado com sucesso. Registro foi deletado com sucesso.
    {
        "code": "200",
        "description": "Opera��o realizada com sucesso!"
    }

    400

    Erro na validação do recebimento da mensagem.

    Verificar se as propriedade json leaveOfAbsenceId está preenchida e com dados válidos no pacote enviado.

    1. Dados de Empresa e Filial,
    2. Dados de Filial e Matrícula,
    3. Formato da Data de Início,
    4. Formato da Hora de Inicio
    5. Codigo do Tipo de Afastamento.
    {
        "code": 400,
        "detailedMessage": "Informação leaveOfAbsenceId ausente ou inválida.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem A chave recebida possui estrutura inválida.
    {
        "code": 400,
        "detailedMessage": "Chave do Afastamento(leaveOfAbsenceId) recebido(a) na URL da requisicao possui estrutura invalida. Estrutura esperada:  companyId;branchId;employeeId;startDate;startTime;endDate;leaveOfAbsenceCode",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem Id do funcionário com estrutura inválida(employeeId).
    {
        "code": 400,
        "detailedMessage": "ID do Funcionario(employeeId) que compoe o(a) Chave do Afastamento(leaveOfAbsenceId) recebido(a) na URL da requisicao possui estrutura invalida. Estrutura esperada: companyId | branchId | Matricula no ERP(Tabela SRA)",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem Id do afastamento (leaveOfAbsenceCode) com estrutura inválida.
    {
        "code": 400,
        "detailedMessage": "Tipo do Afastamento(leaveOfAbsenceCode) que compoe o(a) Chave do Afastamento(leaveOfAbsenceId) recebido(a) na URL da requisicao possui estrutura invalida. Estrutura esperada: companyId | branchId | Tipo do Afastamento no ERP(Tabela RCM)",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem Empresa + Filial inválida.
    {
        "code": 400,
        "detailedMessage": "Empresa + Filial(COMPANYID + BRANCHID) que compoe o(a) Chave do Afastamento(leaveOfAbsenceId) recebido(a) na URL da requisicao nao corresponde a uma empresa/filial do Protheus.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem Data inicio possui formato inválido.
    {
        "code": 400,
        "detailedMessage": "Inicio do Afastamento(startDate) que compoe o(a) Chave do Afastamento(leaveOfAbsenceId) recebido(a) na URL da requisicao possui estrutura invalida. Estrutura esperada: AAAAMMDD",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem Data final possui formato inválido.
    {
        "code": 400,
        "detailedMessage": "Data Final do Afastamento(endDate) que compoe o(a) Chave do Afastamento(leaveOfAbsenceId) recebido(a) na URL da requisicao possui estrutura invalida. Estrutura esperada: AAAAMMDD",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem Matrícula não existe no Protheus(SRA).
    {
        "code": 400,
        "detailedMessage": "ID do Funcionario(employeeId) que compoe o(a) Chave do Afastamento(leaveOfAbsenceId) recebido(a) na URL da requisicao nao corresponde a um funcionario valido no Protheus (Tabela SRA).",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem Tipo de afastamento não existe no Protheus(RCM).
    {
        "code": 400,
        "detailedMessage": "Tipo do Afastamento(leaveOfAbsenceCode) que compoe o(a) Chave do Afastamento(leaveOfAbsenceId) recebido(a) na URL da requisicao nao corresponde a um tipo de afastamento valido no Protheus (Tabela RCM). ",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem Chave não informada está em branco.
    {
        "code": 400,
        "detailedMessage": "Chave do Afastamento(leaveOfAbsenceId) que era esperado(a) na URL da requisicao esta ausente.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    400 Erro na validação do recebimento da mensagem Afastamento referenciado não existe na (SR8)(informou dados incorretos).
    {
        "code": 400,
        "detailedMessage": "O afastamento que deseja alterar nao foi encontrado no Protheus(Tabela SR8), verifique.",
        "helpUrl": "https://tdn.totvs.com/x/ZYNvI",
        "message": "Erro na validação do recebimento da mensagem."
    }
    500

    Erro no acesso ao Endpoint.

    É necessário avaliar se o servidor está funcionando corretamente.
    {
       "errorCode": 500,
       "errorMessage": "Ocorreu uma falha no retorno da informação."
    }


    OBS: Estas mensagens de validações serão retornadas sempre que algum campo passado que seja obrigatório ou que algum campo enviado tenha sua origem de dados em outra tabela e não seja localizado na mesma, vale lembrar que são apenas exemplos de mensagens de erros e podendo variar o nome da propriedade enviada.

    Processo de envio de dados para o sistema Quírons (carga de dados)

    Sistemas Envolvidos

    Descrição dos sistemas envolvidos no contexto de negócio (e que serão envolvidos na integração).

    • Protheus (módulo de Gestão de Pessoas): Módulo responsável pela gestão de pessoas, dependentes de funcionários, dentre outros cadastros pertinentes aos colaboradores.
    • Quírons - NG

    Integração

    O objetivo deste processo é permitir que a área do RH ou área responsável pela Gestão de Pessoas envie os dados dos cadastros de Funcionários, Dependentes e Candidatos para o sistema da NG e assim reduzir o trabalho de inclusão manual de todas as informações dentro do sistema.

    • Benefícios 
      • Normalmente o colaborador responsável inclui as informações dos cadastros acima através de um arquivo (csv, txt) ou até mesmo manualmente. Com este processo de geração de dados isso será feito de forma  automática.
      • Não terá um investimento alto de tempo para o cadastramento, pois os dados já serão enviados através da integração a cada requisição do sistema especialista.
    • Arquitetura (Tecnologia)
      • Toda integração entre o Protheus e o Quírons é feita por intermédio de comunicação direta com os Web Services (que são fixos)  REST(Representation State Transfer) utilizando o formato JSON (JavaScript  Object Notation) de serialização de dados, onde através da ativação do serviço do REST do Protheus esteja disponível para utilizar o serviço.

    Importante: Recomendamos como boa prática, que seja criado um serviço REST específico para esta integração (Protheus x Quiróns). 

    • Premissas e Propriedades
      • Na geração o usuário deverá informar  através dos filtros do sistema quais entidades e quais registros deverão ser enviados;
      • Os dados a serem enviados serão gravados na entidade RJP e serão lidos pelo processo de envio de dados para o sistema NG;
      • Será gerado um LOG informado quais dados foram marcados para a exportação e o usuário poderá guardar esta informação para consulta futura.
      • Quando o dado for enviado para a integração, o campo RJP_DTIN será gravado com a data do envio;

    Ativação/Desativação da integração

    Por padrão esta integração estará em repositório, porém demanda realizar a devida configuração conforme abaixo:

    • Para ativar a integração o parâmetro MV_RHNG deverá estar marcado como verdadeiro (.T.) 
    • Para desativar a integração o parâmetro MV_RHNG deverá estar marcado como falso (.F.) 

    Controle de Ambiente

    Exige que os seguintes pontos sejam revisados:

    • Protheus com sua arquitetura devidamente estruturada.
    • Processo de Schedule configurado com o serviço (GPEM923 -Serviço automático de envio de dados para integração com NG ).

    Controle de Versão

    O grupo TOTVS, representado por suas marcas, irá administrar as demandas de evolução dos layouts e demais ajustes, acordando junto aos solicitantes o prazo de liberação de release.

    Todas as evoluções programadas deverão ser discutidas e aprovadas pelas marcas antes do início do desenvolvimento e somente serão desenvolvidas em caso de concordância das marcas e alinhamento com as diretivas definidas pelo Comitê de Integração TOTVS.

    Suporte

    O suporte aos recursos da Integração será de responsabilidade da linha Protheus, onde será analisada pela equipe de suporte da Totvs.

    Fluxo das Informações

    Esta integração traz a funcionalidade exclusivamente para exportação dos cadastros de funcionários, dependentes e pessoas.

    Cadastro

    Esta integração enviará somente dados previamente existentes nos cadastros de funcionários, dependentes e pessoas.

    Processos

    O sistema da NG disponibilizará uma integração para receber os dados da carga inicial e deverá confirmar o recebimento de cada registro exportado.

    Limitações / Restrições Gerais

    • A integração não contemplará inclusão,alteração e exclusão de registros no Protheus, para isso o usuário deverá acessar o ERP e efetuar as devidas ações manualmente.
    • Cada produto deverá gerar um LOG de inclusão de registros a fim de controlar os dados a serem integrados;
    • data de integração do registro deverá ser enviada em cada processo, permitindo que o Protheus possa marcar o registro como integrado;


    Como realizar a Carga de Dados integração

    Para realizar a carga de dados para o sistema parceiro TOTVS será necessário configurar os seguintes processos:

    • Habilitar a integração;
    • Habilitar o serviço de integração;
    • Selecionar os registros que deverão ser enviados;

    Habilitar a integração


    Para habilitar a integração o parâmetro MV_RHNG deverá estar com a informação verdadeiro (.T.)

    (Acesse a documentação aqui)


    Criação de usuário e senha para integração.


    O usuário, senha e e-mail utilizados na integração são armazenados nos seguintes parâmetros. 

    Parâmetro

    Tipo

    Descrição

    Conteúdo Padrão

    MV_URIQR C Endereço URI do Quirons.
    MV_EMAILQR C Endereço de e-mail para conexão com Quirons.
    MV_SENHAQR C Senha para conexão com Quirons.


    Para a definição de usuário, senha e e-mail é necessário acessar a rotina Parâmetros NG (GPEM926) e preencher parâmetros de acordo com a definição para a integração. 

    Para mais informações acesse, nossas documentações complementares:

    * Criação de parâmetros Quiróns


    Para o envio da carga inicial é necessário habilitar o serviço (GPEM923 - Serviço automático de envio de dados para integração com NG).Este serviço é o responsável por chamar cada integração e enviar os dados para o sistema Quírons da NG).

    (Acesse a documentação aqui)


    Habilitar o serviço de integração

    Selecionar os registros que serão enviados na carga inicial

    Acessar a rotina GPEM925 - Carga Inicial SIGAGPE x Sistema NG.Disponível em: Atualizações\Integrações\Integração Ng\Carga Inicial.


    Ao acessar a rotina será demostrada uma tela de parâmetros para a geração da carga inicial.




    Parâmetros de Entrada
    :
    Parâmetro
    Valor de Exemplo
    Obrigatório
    Tipo
    Parâmetro
    Valor Default
    Descrição
    Filial De:?
    D MG 01
    Não
    String
    query

    Inicio da relação de filiais.
    Filial Até:?
    D MG 01
    Não
    String
    query

    Final da relação de filiais.
    Cadastro de Funcionários
    Check
    Não
    Opção
    query

    Informa que será enviado na carga inicial a relação de funcionários.
    Cadastro de Dependentes
    Check
    Não
    Opção
    query

    Informa que será enviado na carga inicial a relação de funcionários.
    Matrícula De:?
    000001
    Não
    String
    query

    Início da relação de matrículas de funcionários ou dependentes.
    Matrícula Até:?
    999999 Não String query
    Final da relação de matrículas de funcionários ou dependentes.
    Cadastro de Candidatos
    Check Não Opção query
    Informa que será enviado na carga inicial a relação de candidatos.
    Candidato De:?
    000001 Não String query
    Início da relação de códigos de candidatos.
    Candidato Até:?
    999999 Não String query
    Final da relação de códigos de candidatos.
    Log de Processamento
    Check Não Opção query
    Informa se deseja gerar um relatório com o LOG da carga de dados.


    Tela de confirmação do processamento da carga inicial:


    Tela demonstrando que não foram encontrados dados para exportação com o filtro informado:


    Tela demonstrando a quantidade de registros de cada entidade que foram marcados para exportação:


    Tela demonstrando a forma de impressão do LOG:

    Impressão do relatório demonstrando que os registros foram marcados para exportação:


    IMPORTANTE

    *** Caso as entidades funcionáriosdependentes e candidatos tiverem compartilhamentos diferentes, será necessário realizar a exportação individual de cada tabela.