Extrato de Autorizações

Owned by Dáviny Messias Rocha (Unlicensed)
Last updated: nov. 08, 2021 by Geovane Henrique Pinto da Costa
6 min read

Objetivo

Este documento tem como objetivo orientar a construção de um webservice para retornar os dados necessários para demonstrar as autorizações do beneficiário, por status, com a possibilidade de visualizar os detalhes (itens da guia).

Necessidades

Necessidade: Disponibilizar ao beneficiário a relação das suas autorizações, por status, e possibilitar a visualização dos itens da guia e imprimir a guia completa em PDF.

Lista de métodos que serão descritos

extratoAutorizacao: retorna uma lista com todos os protocolos de autorização do beneficiário e do seu grupo familiar, conforme regra de negócio da sua operadora.

detalheAutorizacao: retorna eventos (itens) da guia de autorização (método opcional).

guiaPdf: retorna a URL ou a string BASE64 do arquivo PDF da guia completa.

statusAutorizacao: retorna a tabela de domínio dos status de autorização, para que possamos montar as legendas da listagem.

Informações

AVISOS

1- Só são suportadas integrações no padrão REST.

2- O campo "Regra de preenchimento" esclarece quais regras / validações serão aplicadas ou quais os conteúdos serão permitidos ou rejeitados. As ações descritas aqui devem ser implementadas por seus WS, evitando que os conteúdos inválidos sejam criticados pelo nosso sistema de integrações.

 

CRITÉRIOS DE PREENCHIMENTO

Abreviação

Nome

Descrição

Abreviação

Nome

Descrição

M

Mandatório

O preenchimento do atributo é obrigatório. Caso o atributo esteja nulo ou em branco, seu "response" será rejeitado.

C

Condicional

O atributo pode tornar-se obrigatório quando um ou mais atributos auxiliares for preenchido / atualizado.

OP

Opcional

Seu preenchimento não é obrigatório. Pode-se enviar NULL para objetos, ou arrays vazios para tipos Array.

 

Método "extratoAutorizacao"

Este método irá retornar a lista com todas as solicitações de autorização do usuário, conforme layout que será descrito abaixo. Este método deve retornar o cabeçalho da autorização.

Regras de negócio

  1. Método de construção obrigatória;

  2. O webservice deverá receber os dados necessários para identificação do beneficiário e retornar as suas autorizações e, conforme tipo de usuário, retornar também as autorizações do seu grupo familiar.

  3. Se o beneficiário solicitado for o titular, retornar as suas autorizações e de todo o grupo familiar

  4. Se o beneficiário solicitado for um dependente, retornar apenas as suas próprias autorizações

  5. Opcionalmente, o webservice poderá receber uma data inicial e final e retornar todas as autorizações existentes no período.

  6. Se os parâmetros Data Inicial e Final não forem informados, retorne uma lista com a quantidade de autorizações que desejar, como por exemplo, dos últimos 12 meses.

Parâmetros de entrada

alerta

Será adicionado ao corpo da requisição os dados da chave 'Integracao” do beneficiário retornada no login do mesmo.

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

dataInicial

OP

Date

Data inicial do extrato de autorizações

Formato: YYYY-MM-DD

dataFinal

OP

Date

Data final do extrato de autorizações

Formato: YYYY-MM-DD

Estrutura de retorno

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

status

M

Boolean

True = indica que a requisição foi bem-sucedida

False = Indica que a requisição foi mal sucedida

IMPORTANTE: caso o beneficiário não tenha nenhuma autorização a ser exibida, retorne TRUE neste método (pois a requisição foi bem sucedida). Nesses casos, o objeto autorizações - documentado mais adiante - deverá ser retornado VAZIO.

True 

motivoCritica

C

String

Quando o status for igual a False, envie nesta propriedade o motivo pelo qual não foi possível realizar a requisição. Este campo é obrigatório quando o status igual a False.

Formato: texto livre.

autorizacoes

C

Array de objetos “autorizacoes”

Retornar uma lista de objetos “autorizacao“ (definição abaixo).

 

Definição da estrutura “autorizacao”

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

chaveAutorizacao

M

String

Chave única de identificação da guia de autorização no seu sistema

Formato: Texto livre.

 

beneficiarioMatricula

M

String

Código da matricula do beneficiário da guia

Formato: Texto livre.

beneficiarioNome

M

String

Nome completo do beneficiário da guia

Formato: Texto livre.

statusId

M

Integer

Código do status da autorização, conforme tabela de domínio descrita no método statusAutorizacao

Numérico

dataSolicitacao

M

Date

Data da solicitação

Formato: YYYY-MM-DD

dataAutorizacao

OP

Date

Data da autorização

Formato: YYYY-MM-DD

nomePrestador

M

String

Nome do prestador de serviço

Formato: Texto livre.

especialidade

M

String

Especialidade vinculada ao serviço requisitado

Formato: Texto livre.

tipoTratamento

M

String

Descrição do tipo de tratamento da guia

Formato: Texto livre.

numeroPedido

M

String

Número da guia ou do pedido

Formato: Texto livre.

senha

OP

String

Número da senha de autorização, caso exista

Formato: Texto livre.

Método “detalheAutorizacao”

Retorna os detalhes (itens) de uma guia de autorização.

Regras de negócio

  • O webservice deverá receber a chave da autorização e retornar os dados complementares do protocolo guia.

  • Método de construção opcional, porém caso não seja construído, o usuário do sistema não poderá verificar os detalhes da liberação.

Parâmetros de entrada

Atributo

Critério

Tipo

Descrição

 

Regra de preeenchimento

Atributo

Critério

Tipo

Descrição

 

Regra de preeenchimento

chaveAutorizacao

OP

String

Chave única de identificação da guia de autorização no seu sistema

Formato: texto livre.

Estrutura de retorno

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

status

M

Boolean

True = indica que a requisição foi bem-sucedida

False = Indica que a requisição foi mal sucedida

true

motivoCritica

C

String

Quando o status for igual a False, envie nesta propriedade o motivo pelo qual não foi possível realizar a requisição.

Este campo é obrigatório quando o status igual a False

Formato de texto livre.

itens

C

Array de objetos “itens”

Caso o atributo status seja verdadeiro, este atributo torna-se obrigatório

 

Definição da estrutura item

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

itemId

M

String

Chave única do item da guia de autorização

Formato: texto livre.

procedimento

M

String

Código do procedimento

Formato: texto livre.

procedimentoDescricao

M

String

Descrição do procedimento

Formato: texto livre.

statusId

M

Integer

Descrição do procedimento

Numérico

quantidadeSolicitada

M

Float

Quantidade solicitada

Numérico, 2 posições decimais. Indicador decimal = PONTO (9999999.99)

quantidadeAutorizada

OP

Float

Quantidade autorizada pela operadora

Numérico, 2 posições decimais. Indicador decimal = PONTO (9999999.99)

dataAutorizacao

OP

Date

Data da autorização do procedimento

Formato: “YYYY-MM-DD“

Método “statusAutorizacao”

Retorna a tabela de domínio dos status da autorização, para que possamos montar as legendas da listagem

Regras de negócio

  • Método obrigatório, deve ser construído pela sua empresa.

Parâmetros de entrada

Não é necessário enviar parâmetros para este método.

Estrutura de retorno

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

status

M

Boolean

True = indica que a requisição foi bem-sucedida.

False = Indica que a requisição foi mal sucedida.

true

motivoCritica

C

String

Quando o status for igual a False, envie nesta propriedade o motivo pelo qual não foi possível realizar a requisição.

Este campo é obrigatório quando o status igual a False.

Formato: “texto livre”

autorizacaoStatus

C

Array de objetos “autorizacaoStatus”

Caso o atributo status seja verdadeiro este atributo torna-se obrigatório

 

Definição da estrutura “autorizacaoStatus”.

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

chaveStatus

M

String

Chave única de identificação do status da autorização

Formato: texto livre.

descricao

M

String

Descrição do status

Formato: texto livre.

Método “guiaPdf”

Este método irá retornar uma URL ou uma string BASE64 do arquivo PDF da guia completa.

Observação importante: você pode optar por não desenvolver este método e ao invés disso, fornecer uma URL que recebe os mesmos parâmetros via GET ou via POST e retorna um arquivo PDF pronto para que possamos demonstra-lo no app.

Parâmetros de entrada

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

chaveAutorizacao

M

String

Chave única de identificação da guia de autorização no seu sistema

Formato: texto livre.

Estrutura de retorno

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

status

M

Boolean

True = indica que a requisição foi bem-sucedida.

False = Indica que a requisição foi mal sucedida.

true

motivoCritica

C

String

Quando o status for igual a False, envie nesta propriedade o motivo pelo qual não foi possível realizar a requisição. Este campo é obrigatório quando o status igual a False

Retorna a URL do arquivo PDF no seu servidor. Essa URL precisa ser pública para ser acessada diretamente pelo aplicativo do usuário

binario

C

base64

Retorna conteúdo binário, tipo base64, do arquivo PDF da guia a ser impressa.

Formato: base64.

Caso o atributo url esteja vazio, este atributo torna-se obrigatório

url

C

String

Retorna a URL do arquivo PDF. Essa URL deve ser publica e acessível pela internet sem restrição de firewall. Observação: se o campo BINARIO não for enviado, este campo torna-se obrigatório.

Formato: texto livre

Mobile Saúde - 2019