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 inovações e prestadores de serviços no ramo de benefícios para administrar dentro do RH, empresas e softwares especialistas na administração de benefícios estão cada vez mais presentes no mercado e foi neste contexto que surgiu a necessidade da criação de uma interface para que possibilite automatizar o envio dos dados que hoje são realizados manualmente do ERP para o softwares especialista, seja feito através de uma interface de integração.
O objetivo desta integração é permitir que a área do RH ou área responsável pelos benefícios, envie os dados de funcionários para o sistema da DIVICOM e assim redução no trabalho de inclusão manual de todas as informações dentro do sistema.
Por intermédio desta integração será disponibilizada a seguinte funcionalidade:
Fora do escopo
Por padrão esta integração estará em repositório, porém demanda realizar a devida configuração conforme abaixo:
Exige que os seguintes pontos sejam revisados:
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.
O suporte aos recursos da Integração será de responsabilidade da linha MicroSiga Protheus, onde será analisada pela equipe de suporte da Totvs.
Esta integração traz a funcionalidade exclusivamente de cadastro de funcionários
Esta integração contempla apenas a consulta e envio dos dados de cadastro de funcionários.
A DIVICOM realizará o consumo da API com dados básicos que serão utilizados como parâmetros para consultar a base de funcionários e retornar um conjunto de informações pertinentes ao Cadastro de Funcionário(GPEA010) e retornar os dados para o requisitante.
Para realizar a integração com o parceiro TOTVS é necessário as informações básicas de consulta para retorno dos funcionários desejados.
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 | Sim | Integer | query | Página que está sendo requisitada. | |
pageSize | 1 | Não | Integer | query | 100 | Quantidade de funcionários por página. |
product | PROTHEUS | Sim | String | query | ||
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(RA_USERLGA) | |
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:
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/employeedatacontent/
Response da API:
{ "items": [ { "telephone": " ", "areaCodeMobile": " ", "workCardSerie": "99999", "companyKey": "T1|D MG 01 ", "workShiftSequence": " ", "badgeNumber": " ", "streetNumber": " ", "complement": " ", "branch": "D MG 01 ", "salaryCategory": "M", "roleDescription": "FUNCAO PADRAO ", "workCardNumber": "999999 ", "departamentInternalId": " | ", "socialIntegProgCode": " ", "code": "000001", "neighborhood": " ", "birthDate": "1963-06-10T00:00:00", "costCenterInternalId": "000000001", "zipCode": " ", "areaCode": " ", "name": "JOAO DA SILVA ", "hiringDate": "1999-03-10T00:00:00", "workShiftCode": "001", "city": " ", "roleCode": "00001", "costCenterDescription": "TEC PADRAO ", "gender": "M", "street": "TESTE ", "homeState": "SP", "workCardStateIssuing": "SP", "workShiftInternalId": "D MG |001", "roleInternalId": "D MG |00001", "departamentCode": " ", "demissionDate": "", "costCenterCode": "000000001", "employeePositionDescription": " ", "mobileNumber": " ", "fullName": " ", "employeeSituation": " ", "workshiftDescription": "TURNO UNICO ", "id": "T1|D MG 01 |000001", "employeePositionCode": " ", "employeePositionCodeInternalId": " | ", "naturalCity": "SP", "contractEnd": "", "email": " ", "departmentDescription": " " }], "hasNext": true, "total": 3307 } |
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.
CAMPOS PROTHEUS | PROPRIEDADES API REST | DESCRIÇÃO |
---|---|---|
SM0->M0_CODIGO + "|" + SRA->RA_FILIAL | companyKey | Agrupamento de Empresa, Unidade de negócio e Filial" - SM0->M0_CODIGO |
SRA->RA_FILIAL | branch | Filial do Funcionario |
SRA->RA_MAT | code | Matricula do Funcionario |
SM0->M0_CODIGO + "|" + SRA->RA_FILIAL + "|" + SRA->RA_MAT | id | Chave única do funcionário |
SRA->RA_NOME | name | Nome do Funcionário |
SRA->RA_NOMECMP | fullName | Nome Completo do Funcionário |
SRA->RA_CRACHA | badgeNumber | Número do Crachá |
SRA->RA_DEPTO | departamentCode | Codigo do departamento |
QB_FILIAL + "|" + QB_DEPTO + | departamentInternalId | InternalId do Departamento |
QB_DESCRIC | departmentDescription | Descrição do Departamento |
RA_ADMISSA | hiringDate | Data de Admissão |
RA_DEMISSA | demissionDate | Data de Demissão |
RA_NASC | birthDate | Data de aniversário |
RA_SEXO | gender | Sexo |
RA_ENDEREC | street | Rua do funcionário |
RA_NUMENDE | streetNumber | Número do endereço |
RA_COMPLEM | complement | Complemento do endereço |
RA_BAIRRO | neighborhood | Bairro do Funcionário |
RA_ESTADO | homeState | Estado do Funcinário |
RA_NATURAL | naturalCity | Naturalidade |
RA_SITFOLH | employeeSituation | Situação do Funcionário na Folha |
RA_MUNICIP | city | Cidade do Funcionário |
RA_CEP | zipCode | Número do Cep |
RA_DDDFONE | areaCode | Código de Área(DDD) |
RA_TELEFON | telephone | Telefone |
RA_DDDCELU | areaCodeMobile | Código de Área(DDD) |
RA_NUMCELU | mobileNumber | Número do Telefone Celular |
RA_PIS | socialIntegProgCode | Numero do PIS do Funcionário |
RA_NUMCP | workCardNumber | Carteira de Trabalho do Funcionário |
RA_SERCP | workCardSerie | Serie da Carteira de Trabalho Profissional |
RA_UFCP | workCardStateIssuing | Unidade da federação emitente da carteira de trabalho |
RA_CC | costCenterCode | Código do Centro de Custo |
RA_CC | costCenterInternalId | costCenterInternalId |
CTT_DESC01 | costCenterDescription | Descrição do Centro de Custo |
RA_CARGO | employeePositionCode | Código do Cargo do Funcionário |
SQ3->Q3_FILIAL + "|" + RA_CARGO | employeePositionCodeInternalId | InternalId do Cargo do Funcionário |
Q3_DESCSUM | employeePositionDescription | Descrição do Cargo do Funcionário |
RA_CATFUNC | salaryCategory | Categoria Salarial. Rever estas categorias quando for utilizar com o RM. Produto Datasul também possui outras categorias (Semana, Quinzenal e Diarista) |
RA_TNOTRAB | workShiftCode | Turno de Trabalho |
R6_FILIAL+ "|" + RA_TNOTRAB | workShiftInternalId | O InternalID do Turno de Trabalho |
R6_DESC | workshiftDescription | Descrição do Turno de Trabalho |
RA_SEQTURN | workShiftSequence | Sequência de Turno do funcionário |
RA_CODFUNC | roleCode | Código da Função do Funcionário |
RJ_FILIAL + "|" + RA_CODFUNC | roleInternalId | InternalID do Código da Função do Funcionário |
RJ_DESC | roleDescription | Descrição da Função do Funcionário |
RA_DTFIMCT | contractEnd | Data de término do contrato trabalho/experiência |
RA_EMAIL | Email do funcionário |
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 | API RESPONSE | |
400 | Campo RA_USERLGA não foi encontrado. | Habilitar o campo RA_USERLGA pelo configurador. |
| |
400 | O Produto é um parâmetro obrigatório. | Preencher o parâmetro Produto. |
| |
400 | A Filial é um parâmetro obrigatório. | Preencher o parâmetro Filial. |
|
Mensagens de Pós-Validação
Erro | Mensagem | Solução | API RESPONSE | |
400 | Nenhum registro localizado. | Informar outra data de alteração para ser utilizada na consulta. |
|
Tratamento de Erros Inesperados(TRY/CATCH):
{ "code": 500, "detailedMessage": "", "helpUrl": "http://tdn.totvs.com/x/Uzh_HQ", "message": "Ocorreu uma falha no retorno da informação.\r\nErro ao preparar o ambiente com a Empresa e Filial informados!\r\nSaída no final: Falha de conexão com o banco de dados\r\nContacte o administrador do sistema" } |
Itens a serem verificados durante o atendimento: