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 que torne possível 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 cadastros, enviem seus dados para o sistema da DIVICOM e assim reduz o trabalho de inclusão manual de todas as informações dentro do sistema.
Por intermédio desta integração estará disponível 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 Beneficiários de Plano de Saúde.
Esta integração contempla apenas a consulta e envio dos dados de cadastro de Beneficiários de Plano de Saúde.
A DIVICOM realizará o consumo da API com dados básicos que serão utilizados como parâmetros para consultar a base de beneficiários e retornar um conjunto de informações pertinentes ao Cadastro de Dependentes (GPEA020) e Cadastro de Planos de Saúde Ativos (GPEA001) 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 beneficiá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 | 1 | Página que está sendo requisitada para o retorno. |
pageSize | 1 | Não | Integer | query | 2000 | Quantidade de beneficiários que será retornado por página. |
product | PROTHEUS | Sim | String | query | Parâmetro de entrada para processamento das informações. | |
datemodified | 2019-01-01T00:00:00 | Não | String | query | Data que será utilizada como filtro para trazer beneficiários com data de alteração (RHK_USERGA e RHL_USERGA) maior ou igual ao informado. | |
branchId | D MG 01 | Sim | String | query | Filial que será utilizada no filtro da consulta de Beneficiários. | |
companyId | T1 | Sim | String | query | Empresa que será utilizada no filtro da consulta de Beneficiários. |
A autenticação será do tipo Basic Authorization e será obrigatório (configuração do parâmetro Security = 1 no arquivo appserver.ini).
Página do Serviço REST:
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 e da API Rest, a requisição deverá ser semelhante a imagem abaixo:
Estrutura: {protocolo}://{host:porta}/{rest}/{api}/rh/v1/BeneficiariesDataContent/
Exemplo: http://localhost:8034/rest/api/rh/v1/BeneficiariesDataContent/
Retorno da API:
{ "items": [ { "identityNumber": "", "MaritalState": "", "BenefitCPF": "10084068809", "companyKey": "T1|D MG 01 ", "IdentityNumberEmitterAgency": "", "ContractNumberCode": "", "BenefitVendorSegmentCode": "1", "branch": "D MG 01 ", "BenefitCode": "01", "BeneficiaryTall": "", "beginDate": "012015", "BenefitVendorInternalId": "", "code": "01", "FinalDate": " ", "Birth": "2000-01-01T00:00:00", "MotherName": "", "BornAlive": "1", "DentalAssistanceCardCode": " ", "EmployeeInternalId": "", "BenefitsVendorCode": "001", "Name": "DEPENDENTE 001 ", "SUSCardCode": "1267778459364 ", "Gender": "M", "DegreeOfRelatedness": "F", "EmployeeCode": "000006", "RegistryType": "", "MedicalAssistanceCard": "96845712333 ", "BeneficiaryWeight": "", "BenefitInternalId": "", "ContractNumberInternalId": "", "FoodCardsCode": "", "id": "D MG 01 |000006|01|1|001|1|01", "MealCardsCode": "" } ], "hasNext": true, "total": 10 } |
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 + "|" + RHK->RHK_FILIAL | companyKey | Agrupamento de Empresa, Unidade de negócio e Filial |
Se for Titular usa o campo RHK->RHK_FILIAL e se for Dependente usa o campo RHL->RHL_FILIAL | branch | Filial do Beneficiário |
Se for Titular usa o Default "00" e se for Dependente usa o campo RHL->RHL_CODIGO | code | Código do Beneficiário |
Chave única do Beneficiário, concatenação dos campos de chave única existente na tabela RHK, índice 3(RHK_UNQ), caso seja um titular ou RHL, índice 4(RHL_UNQ), caso seja um Dependente. | id | Chave única do funcionário |
Se for Titular usa o campo RHK_CODFOR e se for Dependente usa o campo RHL_CODFOR | BenefitsVendorCode | Identificador do Fornecedor de Benefícios |
Vazio em ambos os casos. | BenefitVendorInternalId | Identificador Interno do Fornecedor de Benefícios |
Se for Titular usa o campo RHK_TPFORN e se for Dependente usa o campo RHL_TPFORN | BenefitVendorSegmentCode | Código do tipo de segmento do fornecedor do Benefício: 1 - Assistência Médica | 2 - Assistência Odontológica |
Se for Titular usa o campo RHK_PLANO e se for Dependente usa o campo RHL_PLANO | BenefitCode | Código do Benefício |
Vazio em ambos os casos. | BenefitInternalId | Identificador Interno do Benefício |
Se for Titular usa o campo RHK_PERINI e se for Dependente usa o campo RHL_PERINI | beginDate | Início da vigência do Benefício ao beneficiário |
Se for Titular usa o campo RHK_PERFIM e se for Dependente usa o campo RHL_PERFIM | FinalDate | Fim da vigência do Benefício ao beneficiário |
Consulta dados na tabela S074 de acordo com os campos RHK_TPFORN e RHL_TPFORN, caso seja titular ou Dependente respectivamente | ContractNumberCode | Código do Contrato do Plano de Saúde |
Vazio em ambos os casos. | ContractNumberInternalId | Identificador interno do Contrato |
Se for Titular usa o campo RHK_MAT e se for Dependente usa o campo RHL_MAT | EmployeeCode | Identificador do Funcionário |
Vazio em ambos os casos. | EmployeeInternalId | Identificador interno do Funcionário |
Vazio em ambos os casos. | RegistryType | Tipo do Registro do Beneficiário |
Se for Titular usa o Default "T"e se for Dependente usa o campo RB_GRAUPAR | DegreeOfRelatedness | Grau de parentesco do dependente com o Titular: T - Titular, C - Casado, D - desquitado, E - União Estável, I - Divorciado, O - Outros, P - Separado, S - Solteiro, V - Viúvo |
Se for Titular usa o campo RA_NOME e se for Dependente usa o campo RB_NOME | Name | Nome do Beneficiário |
Se for Titular usa o campo RA_CIC e se for Dependente usa o campo RB_CIC | BenefitCPF | CPF do Beneficiário |
Se for Titular usa o campo RA_MAE e se for Dependente recebe vazio. | MotherName | Nome da Mãe do beneficiário titular |
Se for Titular usa o campo RA_SEXO e se for Dependente usa o campo RB_SEXO | Gender | Sexo do beneficiário: M - Masculino, F - Feminino |
Se for Titular usa o campo RA_ESTCIVI e se for Dependente recebe vazio. | MaritalState | Estado Civil C - Casado | D - Desquitado | E - União Estável | I - Divorciado | O - Outros | P - Separado | S - Solteiro | V - Viúvo |
Se for Titular usa o campo RA_NASC e se for Dependente usa o campo RB_DTNASC | Birth | Data de aniversário do beneficiário |
Se for Titular usa o campo RA_RG e se for Dependente recebe vazio. | identityNumber | Identidade da pessoa (RG) |
Se for Titular usa o campo RA_RGEXP e se for Dependente recebe vazio. | IdentityNumberEmitterAgency | Órgão emissor da identidade da pessoa (RG) |
Se for Titular usa o campo RHK_MATSAU e se for Dependente usa o campo RHL_MATSAU | MedicalAssistanceCard | Número do Cartão de Assistência Médica |
Se for Titular usa o campo RHK_MATODO e se for Dependente usa o campo RHL_MATODO | DentalAssistanceCardCode | Número do Cartão de Assistência Odontológica |
Vazio em ambos os casos. | FoodCardsCode | Número do Cartão para Alimentação |
Vazio em ambos os casos. | MealCardsCode | Número do Cartão para Refeição |
Se for Titular usa o campo RHK_CNS e se for Dependente usa o campo RHL_CNS | SUSCardCode | Número do Cartão do SUS |
Em ambos os casos recebem o valor Default "1" | BornAlive | Flag que determina se o beneficiário foi nascido vivo: 1 - Nascido Vivo , 0 - Não Nascido Vivo |
Vazio em ambos os casos. | BeneficiaryWeight | Peso em (gr) do Beneficiário |
Vazio em ambos os casos. | BeneficiaryTall | Altura em (cm) do beneficiá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 | "Os campos RHK_USERGA, RHL_USERGA, RHK_MATSAU, RHK_MATODO, RHK_CNS, RHL_MATSAU, RHL_MATODO e RHL_CNS são obrigatórios e não foram encontrados. | Habilitar pelo configurador os campos citados na mensagem de Erro. |
| |
400 | O parâmetro product é obrigatório. | Preencher o parâmetro product. |
| |
400 | O parâmetro branchId é obrigatório | Preencher o parâmetro branchId. |
| |
400 | O parâmetro companyId é obrigatório. | Preencher o Parâmetro companyId. |
| |
400 | Se preenchido, o parâmetro datemodified deve estar no formato: '2019-05-01T18:25:43'. | Preencher o Parâmetro datemodified no formato padrão. |
| |
400 | Filial não encontrada para os valores informados de empresa e Filial: XX X XX XX | Preencher uma filial válida. |
|
Mensagens de Pós-Validação
Erro | Mensagem | Solução | API RESPONSE | |
400 | Nenhum registro localizado. | Informar uma data(datemodified) que contenham registros alterados(RHK_USERGA e RHL_USERGA). |
|
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: