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 Datasul, 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(Coparticipações) retornados por página. |
product | DIVICOM | 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 | 180 | Sim | String | query | Estabelecimento que será utilizada como filtro para retorno das Coparticipações. | |
companyId | 10 | 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 a utilização de um usuário e senha válido no TOTVS Datasul.
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 TOTVS Datasul API Rest, a requisição deverá ser semelhante a imagem abaixo:
{protocolo}://{host:porta}/{rest}/{api}/rh/v1/BeneficiariesCoparticipation/
Exemplo: http://187.94.56.228:8080/api/rh/v1/BeneficiariesCoparticipation?companyId=10&branchId=180&product=DIVICOM
Response da API:
{ "data": { "total": 1, "items": [ { "MedicalAssistanceCard": "", "MaritalState": "C", "IdentityNumberEmitterAgency": "SSP", "DentalAssistanceCardCode": "", "BenefitsVendorCode": "11", "beneficiaryWeight": "84", "identityNumber": "253428221", "code": "6503", "MotherName": "TERESA ROSELI BELARMINO MARIANNO", "beginDate": "2013-10-01T00:00:00", "ContractNumberCode": "C-UNI-123456", "EmployeeCode": "6503", "BenefitCPF": "15538279880", "id": "10|180|6503", "DegreeOfRelatedness": "T", "Name": "NERO PINHEIRO", "Birth": "1975-04-03T00:00:00.000", "SUSCardCode": "898000496776012", "RegistryType": "0", "companyKey": "10", "Gender": "M", "BornAlive": "1", "branch": "180", "FinalDate": "9999-12-01T00:00:00", "BenefitVendorSegmentCode": "1", "beneficiaryTall": "1,78", "BenefitCode": "300" } ], "hasNext": true }, "length": null, "messages": [] } |
Dados utilizados da API
Por ser uma estrutura única para todos os produtos, há dados que existem em um produto (RM e/ou Protheus) e não existe no TOTVS Datasul, desta forma cada produto utilizará os campos pertinentes aos seus ambientes.
CAMPOS Datasul | PROPRIEDADES API REST | DESCRIÇÃO |
---|---|---|
Chave da tabela COPART_FUNC para localizar o registro que será retornado ao serviço chamador (copart_func.cdn_empresa | copart_func.cdn_estab | copart_func.cdn_funcionario | copart_func.cdn_depend_func) | Id | Chave da tabela COPART_FUNC para localizar o registro que será retornado ao serviço chamador |
copart_func.cdn_empresa | CompanyKey | Informação referente a Empresa do lançamento da Coparticipação do Beneficiário |
copart_func.cdn_estab | Branch | Informação referente a Filial (Estabelecimento) do lançamento da Coparticipação do Beneficiário |
copart_func.cdn_funcionario | EmployeeCode | Matrícula do funcionário refente ao lançamento da Coparticipação do Beneficiário |
funcionario.nom_pessoa_fisic | EmployeeName | Nome do Funcionário refente ao lançamento da Coparticipação do Beneficiário |
copart_func.cdn_depend_func | DependentCode | Matrícula do Dependente do Beneficiário refente ao lançamento da Coparticipação |
Vazio | DependentName | Informação enviada na TAG EmployeeName. |
depend_func.idi_grau_depen_func | DegreeEmployeeDependency | Grau de dependência do Funcionário no Datasul |
copart_func.dat_ocor | OccurrencyDate | Data em que ocorreu o lançamento do evento da Coparticipação no Produto TOTVS |
copart_func.cdn_prestdor_serv | ServiceProvider | Código do Prestador de Serviço dentro do Produto TOTVS |
copart_func.idi_contrat_prestdor | ServiceProviderContractType | Tipo de Contrato da Prestadora de Serviço: 1 - Assistência Médica | 2 - Assistência Odontológica | 3 - VR | 4 - VA | 5 - VT | 9 - Outros |
copart_func.cod_contrat_prestdor | ServiceProviderContract | úmero do Contrato do Prestador de Serviço relacionado ao lançamento da Coparticipação do beneficiário |
copart_func.copart_func.val_copart | CoparticipationValue | Valor referente ao lançamento da coparticipação do beneficiário no Produto TOTVS |
copart_func.num_ano_mes_refer | YearMonthReference | Ano e mês de referência do lançamento da Coparticipação do Beneficiário no Produto TOTVS |
copart_func.cod_id_feder_prestdor | ServiceProviderId | CNPJ do Prestador de Serviço referente ao lançamento da coparticipação do beneficiário no Produto TOTVS |
copart_func.nom_prestdor | ServiceProviderName | Nome do Prestador de Serviço referente ao lançamento da coparticipação do beneficiário no Produto TOTVS |
copart_func.nom_especialid | SpecialtyName | Nome da especialidade do Prestador de Serviço referente ao lançamento da Coparticipação do Beneficiário no Produto TOTVS |
copart_func.cod_cid | InternationalCodeDiseases | Código internacional de Doenças lançado da Coparticipação do Beneficiário no Produto TOTVS |
copart_func.idi_tip_atend. | 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 |
copart_func.qti_utiliz | AmountUse | Quantidade de utilização de coparticipação por parte do beneficiário e seus dependentes dentro do Produto TOTVS |
copart_func.des_copart | CoparticipationDescription | Descrição da Coparticipação referente ao lançamento no histórico do beneficiário no Produto TOTVS |
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 |
17006 | Parâmetro 'product' incorreto. | Informar DIVICOM de forma fixa no parâmetro 'product'. | |
17006 | O parâmetro 'companyId' incorreto. | Preencher o parâmetro 'companyId'. | |
17006 | O parâmetro 'branchId' incorreto. | Preencher o parâmetro 'branchId'. | |
17006 | Empresa/Estabelecimento inválidos! | Informar valores válidos no TOTVS Datasul para os parâmetros companyId e branchID |
Mensagens de Pós-Validação
Erro | Mensagem | Solução | API RESPONSE |
17006 | Nenhum registro localizado. | Favor informar corretamente os parâmetros para que os dados do TOTVS Datasul sejam corretamente retornados. |
Itens a serem verificados durante o atendimento: