API UserUsage - Utilização de Beneficiário

CONTEÚDO

Visão Geral
Configurações INI
Verbos
Query Params - GET
Atributos de Resposta
Exemplos de JSONs de Resposta
Pontos de Entrada

01. VISÃO GERAL

A API UserUsage tem como objetivo retornar a utilização do plano de saúde de um beneficiário. A API recebe parâmetros como a matrícula, período de e até, e retorna os eventos executados pelo beneficiário no período informado.

Os registros listados são provenientes de uma Query executada na tabela BD6.

02. CONFIGURAÇÕES INI

Para iniciar a instalação do processo, devemos configurar seu INI Protheus com a funcionalidade REST para habilitar o acesso as API´s. Documentos auxiliares:

Configurando o REST

Com o INI Protheus configurado, a nomenclatura das API´s ficará no formato: <url + Porta + chave rest definidos no INI Protheus> + /totvsHealthPlans/v1/userUsage. Exemplo:

Logo, a minha URL será: http://localhost:8080/rest/totvsHealthPlans/v1/userUsage

03. VERBOS

Seguem os verbos disponíveis na API:

Verbo	Path	Descrição
GET	/userUsage	Extrato de utilização de beneficiários de saúde

04. QUERY PARAMS - GET

Lista de query params obrigatórios:

Campo	Descrição
subscriberId	Matrícula do beneficiário
initialPeriod	Período inicial no formato YYYYMM
finalPeriod	Período final no formato YYYYMM

Exemplo de chamada para utilização de um beneficiário em Dezembro de 2017:

http://localhost:8080/rest/totvsHealthPlans/v1/userUsage?subscriberId=00010001000003002&initialPeriod=201712&finalPeriod=201712

Lista de query params não obrigatórios:

Campo	Descrição
fields	Indica os campos que serão retornados na consulta.
order	Indica uma lista de atributos para realizar a ordenação dos registros. Indicando o caracter – no início, indica que será realizado uma ordenação decrescente. Lista de atributos que são passíveis de ordenação: procedureCode, procedureName, executionDate, subscriberName, healthProviderCode, healthProviderName, quantity, healthProviderDocument, cid, procedureName, healthProviderName, toothRegion, face.
pageSize	Indica quantos registros serão retornados na requisição. O padrão do sistema são 20 registros. Caso ainda existam registros para serem exibidos, o atributo hasNext será retornado com true.
page	Indica a página de ordenação que os registros serão apresentados. Se atentar ao controle booleano hasNext
procedureCode, executionDate, healthProviderCode, healthProviderDocument, cid, procedureName, healthProviderName, quantity, toothRegion, face	Indicando um desses atributos e um valor, a API realizará um filtro adicional com o atributo e valor informado.

05. ATRIBUTOS DE RESPOSTA

Atributo	Campo	Tipo	Descrição
procedureCode	BD6_CODPRO	String	Código do procedimento
procedureName	BD6_DESPRO	String	Descrição do procedimento
executionDate	BD6_DATPRO	String	Data do evento no formato yyyy-mm-dd
subscribername	BD6_NOMUSR	String	Nome do beneficiário
healthProviderCode	BD6_CODRDA	String	Código da rede de atendimento
healthProviderName	BD6_NOMRDA	String	Nome da rede de atendimento
serviceType	BR8_CLASSE	String	Código da classe de procedimento
serviceTypeDescription	BJE_DESCRI	String	Descrição da classe de procedimento
quantity	BD6_QTDPRO	Number	Quantidade do evento
healthProviderDocument	BD6_CPFRDA	String	CPF/CNPJ da rede de atendimento
cid	BD6_CID	String	CID principal do atendimento
toothRegion	BD6_DENREG	String	Região do dente
face	BD6_FADENT	String	Face do dente
paidValue	BD6_VLRPAG	Number	Valor pago
disallowanceValue	BD6_VLRGLO	Number	Valor de glosa
coPaymentValue	BD6_VLRTPF	Number	Valor de co-participação
subscriberId	BD6_OPEUSR+BD6_CODEMP+BD6_MATRIC+BD6_TIPREG+BD6_DIGITO	String	Matrícula do beneficiário
origin	Iif(BD6_TIPGUI = '04', 'REEMBOLSO', 'CONVENIO') as BD6_TIPGUI	String	Origem
procedureType	BR8_TPPROC	String	Tipo do Procedimento
gender	BA1_SEXO	String	Sexo; M (Masculino) e F (Femino)
birthDate	BA1_DATNAS	String	Data de Nascimento
inclusionDate	BA1_DATINC	String	Data de Inclusão
blockDate	BA1_DATBLO	String	Data de Bloqueio
userType	BA1_TIPUSU	String	Tipo do Usuário; T (Titular) e D (Dependente)
countyCode	BA1_CODMUN	String	Código do Município (Padrão IBGE)
hospitalizationNumber	(CASE BD6_TIPGUI WHEN '03' THEN BD6_OPEINT + BD6_ANOINT + BD6_MESINT + BD6_NUMINT ELSE '' END) AS GUIAINT	String	Número da Guia de Internação (Caso seja uma Internação)
status	(CASE BA1_DATBLO WHEN '' THEN 'A' ELSE 'I' END) AS STATUS	String	Status; A (Ativo) e I (Inativo)

06. EXEMPLOS DE JSONS DE RESPOSTA

Sucesso 202

{
    "items": [
        {
            "healthProviderDocument": "34391654857",
            "paidValue": 90.64,
            "subscriberId": "00010001000003002",
            "face": "",
            "coPaymentValue": 0,
            "procedureCode": "10101012",
            "executionDate": "2017-12-27",
            "subscribername": "RENATA",
            "healthProviderName": "RDA SILVIA SANT'ANNA",
            "serviceTypeDescription": "CONSULTAS",
            "serviceType": "000001",
            "cid": "A00",
            "procedureName": "CONSULTA EM CONSULTORIO",
            "healthProviderCode": "000007",
            "disallowanceValue": 44.87,
            "quantity": 1,
            "toothRegion": "",
			"origin": "CONVENIO"
        }
    ],
    "hasNext": false
}

Erro 400

{
    "code": 400,
    "message": "Os parametros abaixo devem ter 6 caracteres: ",
    "detailedMessage": "initialPeriod, finalPeriod",
    "helpUrl": "",
    "details": [
        {
            "code": "",
            "message": "",
            "detailedMessage": "",
            "helpUrl": ""
        }
    ]
}

07. PONTOS DE ENTRADA

Foi desenvolvido o Ponto de Entrada PUTZBEN1, que permite trocar a Query padrão de busca dos registros BD6 por uma customizada:

Ponto de Entrada	PUTZBEN1
Fonte	PLUtzUsDao
Parâmetros	paramixb[1] → cQuery (Caracter) - Query padrão da rotina
Retorno	cQuery (Caracter) → Query padrão manipulada pelo usuário

Exemplo PUTZBEN1

#INCLUDE "TOTVS.CH"

User Function PUTZBEN1()

	Local cQuery := paramixb[1]

	//Ajuste de query do cliente

Return cQuery

Árvore de páginas