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 possibilitar a automatização e 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 a área responsável pelos benefícios, envie os dados de coparticipações para o sistema da DIVICOM e assim reduzir o 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 coparticipação
Esta integração contempla apenas a consulta e envio dos dados do cadastro de coparticipação.
A DIVICOM realizará o consumo da API com dados básicos que serão utilizados como parâmetros para consultar a base de coparticipações e retornar um conjunto de informações pertinentes ao Cadastro de Coparticipação 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 das coparticipações desejadas.
As Entradas e Saídas de dados tipo data(Date) acompanham o formato padrão YYYY-MM-DDThh:mm:ss
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. |
pageSize | 1 | Não | Integer | query | 2000 | Quantidade de registros(Coparticioações) retornados por página. |
product | PROTHEUS | Sim | String | query | Parâmetro de Entrada para registro de origem, atualmente não interfere no retorno das informações. | |
datemodified | 2001-01-01T18:25:43 | Não | String | query | Data que será utilizada como filtro para retorno das coparticipações. | |
branchId | D MG 01 | Sim | String | query | Filial que será utilizada como filtro para retorno das coparticipações. | |
companyId | T1 | Sim | String | query | Empresa que será utilizada como filtro para retorno das coparticipações. |
A autenticação será do tipo Basic Authorization e será obrigatório (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:porta}/{rest}/{api}/rh/v1/BeneficiariesCoparticipation/
Exemplo: http://localhost:8034/rest/api/rh/v1/BeneficiariesCoparticipation
Response da API:
{ "items": [ { "EmployeeCode": "000006", "DependentCode": "00", "SpecialtyName": "81", "companyKey": "T1|D MG 01 ", "ServiceProviderName": "S016 I", "ServiceProviderId": "46942851000154", "CoparticipationValue": "99.00", "EmployeeName": "FUNCIONARIO TESTE API COPART. ", "DependentName": "FUNCIONARIO TESTE API COPART. ", "branch": "D MG 01 ", "DegreeEmployeeDependency": "", "OccurrencyDate": "2015-11-17T00:00:00", "CoparticipationDescription": "", "ServiceProviderContractType": "1", "InternationalCodeDiseases": "Z88.1", "AmountUse": "1", "YearMonthReference": "201901", "ServiceType": "3", "ServiceProviderContract": "", "ServiceProvider": "001", "id": "T1|D MG 01 |000006|2015-11-17T00:00:00|1|001|1| |410|201901" }, { "EmployeeCode": "000006", "DependentCode": "01", "SpecialtyName": "19", "companyKey": "T1|D MG 01 ", "ServiceProviderName": "S016 I", "ServiceProviderId": "46942851000154", "CoparticipationValue": "9999.00", "EmployeeName": "FUNCIONARIO TESTE API COPART. ", "DependentName": "DEPENDENTE 001", "branch": "D MG 01 ", "DegreeEmployeeDependency": "F", "OccurrencyDate": "2015-11-17T00:00:00", "CoparticipationDescription": "", "ServiceProviderContractType": "1", "InternationalCodeDiseases": "Z88.1", "AmountUse": "1", "YearMonthReference": "201901", "ServiceType": "10", "ServiceProviderContract": "", "ServiceProvider": "001", "id": "T1|D MG 01 |000006|2015-11-17T00:00:00|1|001|2|01|504|201901" } ], "hasNext": true, "total": 4 } |
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 + "|" + Se for período aberto usa o campo RHO->RHO_FILIAL e se for perído fechado usa o campo RHP->RHP_FILIAL. | companyKey | Agrupamento de Empresa, Unidade de negócio e Filial. |
Se for período aberto usa o campo RHO->RHO_FILIAL e se for perído fechado usa o campo RHP->RHP_FILIAL. | branch | Filial referente a coparticipação lançada. |
Chave única que identifica os registros dos lançamentos de coparticipações. Se for período aberto usa o índice 4(RHOT10_UNQ) da tabela RHO e se for período fechado usa o índice 3(RHPT10_UNQ) da tabela RHP. | id | Chave única da Coparticipação |
Se perído aberto usa o campo RHO_MAT e se fechado usa o campo RHP_MAT | EmployeeCode | Matrícula do Funcionário. |
Utiliza o campo RA_NOME da tabela SRA. | EmployeeName | Nome do Funcionário. |
Se perído aberto usa o campo RHO_CODIGO e se fechado usa o campo RHP_CODIGO. Em ambos os casos, se o valor for vazio então será retornado "00". | DependentCode | Código identificador do Dependente. |
Se for Titular usa o campo RA_NOME da tabela SRA e se for Dependente usa o campo RB_NOME da tabela SRB. | DependentName | Nome do Beneficiário. |
Se for Titular retorna vazio e se for Dependente usa o campo RB_GRAUPAR da tabela SRB. | DegreeEmployeeDependency | Grau de dependência do Funcionário |
Se período aberto usa o campo RHO_DTOCOR e se fechado usa o campo RHP_DTOCOR. | OccurrencyDate | Data de ocorrência do lançamento da coparticipação para o beneficiário. |
Se período aberto usa o campo RHO_CODFOR e se fechado usa o campo RHP_CODFOR. | ServiceProvider | Identificador do Prestador de Serviço. |
Se período aberto usa o campo RHO_TPFORN e se fechado usa o campo RHP_TPFORN. | ServiceProviderContractType | Tipo de Contrato do Prestador de Serviço indicado no lançamento da Coparticipação do Beneficiário: 1 - Assistência Médica | 2 - Assistência Odontológica | 3 - VR | 4 - VA | 5 - VT | 9 - Outros |
Se período aberto usa o campo RHO_VLRFUN e se fechado usa o campo RHP_VLRFUN. | CoparticipationValue | Valor referente ao lançamento da coparticipação do beneficiário. |
Se período aberto usa o campo RHO_COMPPG e se fechado usa o campo RHP_COMPPG. | YearMonthReference | Ano e mês de referência do pagamento do lançamento da coparticipação do beneficiário. |
Se período aberto usa o campo RHO_CID e se fechado usa o campo RHP_CID. | SpecialtyName | Código internacional de Doenças lançado na coparticipação do beneficiário |
Se período aberto usa o campo RHO_DESPE e se fechado usa o campo RHP_DESPE. | InternationalCodeDiseases | Nome da especialidade do Prestador de Serviço referente ao lançamento da coparticipação do beneficiário. |
Se período aberto usa o campo RHO_TPATEN e se fechado usa o campo RHP_TPATEN. . | ServiceType | Tipo de Atendimento informado pelo Prestador de Serviço no lançamento da Coparticipação do Beneficiário: 1 - Eletivo | 2 - PS | 3 - Exame | 4 - PAC | 5 - Material/Medicamento | 6 - Internação | 7 - Terapia | 8 - Taxa/Diária| 9 - Case | 10 - Reembolso | 11 - Remoção | 12 - Não Informado | 13 - Ambulatório |
Vazio em ambos os casos. | CoparticipationDescription | Descrição da Coparticipação referente ao lançamento no histórico do beneficiário. |
"1" em ambos os casos. | AmountUse | Quantidade de utilização de coparticipação por parte do beneficiário e seus dependentes. |
Número do contrato retornado da tabela S074 de acordo com o código do fornecedor e Tipo de Fornecedor (RHO_CODFOR e RHO_TPFORN para periodo aberto ou RHP_CODFOR e RHP_TPFORN para período fechado). | ServiceProviderContract | Número do Contrato do Prestador de Serviço indicado no lançamento da Coparticipação do Beneficiário |
CNPJ do Prestador de Serviço de acordo com o tipo de Plano, retornado da tabela S016, se for Plano Médico, ou da tabela S017, se for Plano Odontológico, conforme código do fornecedor cadastrado (RHO_CODFOR para período aberto ou RHP_CODFOR para período fechado). | ServiceProviderId | CNPJ do Prestador de Serviço referente ao lançamento da coparticipação do beneficiário |
Nome do Prestador de Serviço de acordo com o tipo de Plano, retornado da tabela S016, se for Plano Médico, ou da tabela S017, se for Plano Odontológico, conforme fornecedor cadastrado (RHO_CODFOR para período aberto ou RHP_CODFOR para período fechado). | ServiceProviderName | Nome do Prestador de Serviço referente ao lançamento da coparticipação 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 RHO_CDESPE, RHO_CID, RHO_TPATEN, RHP_CDESPE, RHP_CID e HP_TPATEN são obrigatórios. | Habilitar os campos RHO_CDESPE, RHO_CID, RHO_TPATEN, RHP_CDESPE, RHP_CID e HP_TPATEN. |
| |
400 | O Produto é um parâmetro obrigatório. | Preencher o parâmetro product. |
| |
400 | A Filial é um parâmetro obrigatório. | Preencher o parâmetro banchId. |
|
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: