APIs para Integração com o APP da Unimed Brasil

CONTEÚDO

Visão Geral
APIs
1. APIs Disponíveis
2. Parâmetros
3. Autenticação
CPCs
Homologação 12.1.26

01. VISÃO GERAL

O TOTVS Saúde Planos (Linha Datasul) oferece uma série de APIs para integração com o APP da Unimed Brasil.

As APIs foram desenvolvidas seguindo as definições disponibilizadas no Swagger da Unimed Brasil.

02. APIs

APIs disponíveis:

As APIs estão disponíveis em um dos seguintes contextos, dependendo do servidor de aplicação utilizado pelo cliente.

TOMCAT: http://<CONTEXTO-TOTVS:PORTA>/api/appUnimedBrasil

JBOSS: http://<CONTEXTO-TOTVS:PORTA>/healthmanagementwebservices/rest/appUnimedBrasil

API	Método	Rota	Documentação
Beneficiário - Autorizações: Beneficiario/AutorizacoesPeriodo	GET	/Beneficiario/v1/AutorizacoesPeriodo	API Autorizações do Beneficiário por Período
Beneficiário - Extrato de coparticipação: Beneficiario/PeriodosDemonstrativoCoparticipacao	GET	/Beneficiario/v1/PeriodosDemonstrativoCoparticipacao	API Extrato de Coparticipação do Beneficiário/Períodos
Beneficiário - Extrato de coparticipação: Beneficiario/DemonstrativoCoparticipacao	GET	/Beneficiario/v1/DemonstrativoCoparticipacao	API Extrato de Coparticipação do Beneficiário
Beneficiário - IRPF: Beneficiario/IRPFAnoBase	GET	/Beneficiario/v1/IRPFAnoBase	API Extrato de IRPF Ano Base
Beneficiário - IRPF: Beneficiario/IRPF **	GET	/Beneficiario/v1/IRPF
Beneficiário - 2ª via de boleto: Beneficiario/SegundaViaBoleto	GET	/Beneficiario/v1/SegundaViaBoleto
Beneficiário - 2ª via de boleto: Beneficiario/Titulos *	GET	/Beneficiario/v1/Titulos
Beneficiário - Histórico boletos: Beneficiario/TitulosLiquidados	GET	/Beneficiario/v1/TitulosLiquidados	API Beneficiário - Histórico de Boletos - Títulos Liquidados
Beneficiário - Extrato de Utilização: Beneficiario/PeriodosExtrato	GET	/Beneficiario/v1/PeriodosExtrato	API Extrato de Utilização do Beneficiário/Períodos
Beneficiário - Extrato de Utilização: Beneficiario/PeriodosExtrato	GET	/Beneficiario/v1/Extrato	API Extrato de Utilização do Beneficiário

* Para Clientes que utilizam o Boletos padrão do produto, o atributo linhaDigitavel só será retornado para títulos cujo lote de boletos já tenha sido gerado (processo de geração) e o download (momento em que é criado o PDF ou TXT) já tenha sido finalizado.

**Para apresentar esse demonstrativo são utilizados os dados enviados na DMED. Dessa forma, sempre que for gerado o arquivo da DMED será carregada uma tabela com a competência e valores para apresentação no demonstrativo do IRPF.

Parâmetros:

Algumas dessas APIs esperam receber alguns parâmetros via header ou via query parameters.

API	Parâmetro	Tipo Parâmetro	Tipo de dados	Formato	Obrigatório?
AutorizacoesPeriodo	dtInicio	Query Parameter	string	dd/mm/aaaa	Sim
AutorizacoesPeriodo	dtFim	Query Parameter	string	dd/mm/aaaa	Sim
DemonstrativoCoparticipacao	periodoId	Query Parameter	string	*	Sim
IRPF	ano	Query Parameter	integer	9999	Sim
SegundaViaBoleto	tituloId	Query Parameter	string	*	Sim
Extrato	periodoId	Query Parameter	string	*	Sim

* O formato desses valores é definido pelo retorno das APIs PeriodosDemonstrativoCoparticipacao e Títulos, que retornam os IDs utilizados para alimentar esses parâmetros.

Além desses parâmetros, todas as APIs exigem que seja informado ao menos um dos cabeçalhos abaixo no header da requisição:

Cabeçalho	Tipo de dados	Formato
X-Carteira	String	99999999999999999
X-CPF	String	99999999999

Situações comuns

Retorno: Status 200, "DebugMessage": "1 - Necessario informar a carteira ou CPF do beneficiario;\\n;" → Faltou adicionar o header X-CPF ou X-Carteira com o formato String

Retorno: Status: 400, "detailMessage": "Method not found" → Pode ocorrer pois não foi especificado o formato do header X-CPF ou X-Carteira

Retorno: Status 404 → Revisar a URL que está sendo chamada.

Autenticação:

As APIs são protegidas via Basic Authentication, utilizando um usuário e senha válidos do TOTVS Planos - Linha Datasul.

Para utilizar as APIs, o usuário e senha devem ser enviados em base64 no formato usuario:senha no cabeçalho de autenticação do tipo Basic.

Exemplo de uma requisição requisição com Basic Authentication onde o usuário é "user" e a senha "password", resultando em um base64 = "dXNlcjpwYXNzd29yZA==":

Request

curl -b cookie.txt -c cookie.txt --location --request GET 'http://<CONTEXTO-TOTVS:PORTA>/api/appUnimedBrasil/Beneficiario/v1/IRPF?ano=2020' \
--header 'x-CPF: 98765432100' \
--header 'Authorization: Basic dXNlcjpwYXNzd29yZA=='

Importante

No exemplo acima, os parâmetros "-b cookie.txt -c cookie.txt " foram incluídos para manter os cookies, pois a autenticação padrão do JBOSS exige a gravação de cookies.

Para contornar essa situação é que foi desenvolvido o contexto "/healthmanagementwebservices/rest/appUnimedBrasil", que deve ser utilizado apenas por operadoras com servidor de aplicação JBOSS afim de dispensar a gravação de cookies pelo client (no caso, o app).

Operadoras que utilizem servidor de aplicação TOMCAT podem utilizar o contexto "/api/appUnimedBrasil" para a chamada das APIs com autenticação "basic auth" normalmente pois o novo framework não exige a gravação de cookies pelo client.

Situações comuns

Caso utilizado o Postman informando o usuário e senha na aba authorization deve ser informado o usuário e senha sem converter pois o Postman converte e adiciona automaticamente o header conforme descrito na explicação a cima.

03. CPCs

Cada API possui dois pontos de CPC. Um no início do processo que permite sobrescrever total ou parcialmente a lógica do produto padrão e outro ao final do processo que permite fazer ajustes nos dados antes de enviar a resposta da requisição.

Para utilizar as CPCs, primeiramente deverá importar o arquivo DZLIBPRX.D (download) através do menu "Importação CPC" (HCG0210Z). Após, habilitar os pontos de CPC desejados através do menu "Manutenção CPC" (HTE0110L) e desenvolver a lógica da cada um dos pontos de chamada no programa da CPC correspondente.

Abaixo a listagem das CPCs disponíveis juntamente com o manual de cada ponto de CPC e um programa de exemplo.

API	Pontos de CPC	Nome Rotina da CPC
Beneficiario/AutorizacoesPeriodo	ANTES-PROCESSO DEPOIS-PROCESSO	BOSAUAUTORIZACOESPERIODO
Beneficiario/PeriodosDemonstrativoCoparticipacao	ANTES-PROCESSO DEPOIS-PROCESSO	BOSAUPERIDEMONSTCOPART
Beneficiario/DemonstrativoCoparticipacao	ANTES-PROCESSO DEPOIS-PROCESSO	BOSAUDEMONSCOPART
Beneficiario/IRPFAnoBase	ANTES-PROCESSO DEPOIS-PROCESSO	BOSAUIRPFANOBASE
Beneficiario/IRPF	ANTES-PROCESSO DEPOIS-PROCESSO	BOSAUIRPF
Beneficiario/SegundaViaBoleto	ANTES-PROCESSO DEPOIS-PROCESSO	BOSAUSEGUNDAVIABOLETO
Beneficiario/Titulos	ANTES-PROCESSO DEPOIS-PROCESSO	BOSAUTITULOS
Beneficiario/TitulosLiquidados	ANTES-PROCESSO DEPOIS-PROCESSO	BOSAUTITULOSLIQUIDADOS
Beneficiario/PeriodosExtrato	ANTES-PROCESSO DEPOIS-PROCESSO	BOSAUPERIODOSEXTRATO
Beneficiario/Extrato	ANTES-PROCESSO DEPOIS-PROCESSO	BOSAUEXTRATO

04. Homologação 12.1.26

Abaixo os programas disponíveis para Homologação na 12.1.26. É necessário estar atualizado com o último patch disponível no console oficial de atualização.

Observação: Para a homologação do item IRPF é necessário aplicar, momentaneamente, o delta em uma tabela especifica e realizar a compilação dos programas .p. Com a aplicação da tabela liberada antecipadamente em um banco específico, ao ocorrer a expedição da tabela oficialmente não acontecerá erros no console oficial de atualização.

É necessário atualizar o jar datasul-hgp-webservices-12.1.26-SNAPSHOT.jar no caminho:
..\ServidorAplicacao\jboss-4.2.3.GA\server\<INSTANCE>\deploy\datasul-byyou-<VERSÂO>-SNAPSHOT.ear\datasul-hgp-webservices-<VERSÂO>-SNAPSHOT.war\WEB-INF\lib

Também é necessário reiniciar a aplicação para que as alterações tenham efeito.

12.1.26-gp350e58p11mt.zip

05. Clientes na 12.1.29 e 12.1.31 com JBOSS

É necessário atualizar o jar disponibilizado no pacote abaixo no seguinte caminho do JBOSS:
..\ServidorAplicacao\jboss-4.2.3.GA\server\<INSTANCE>\deploy\datasul-byyou-<VERSÂO>-SNAPSHOT.ear\datasul-hgp-webservices-<VERSÂO>-SNAPSHOT.war\WEB-INF\lib