4: API para Extrato de Utilização

Caso sua empresa deseje exibir informações de utilização do beneficiário e de seu grupo familiar, ou ainda implementar a funcionalidade de PIN-SS Utilização, esta API deverá ser implementada.

1 Método "extrato"
- 1.1 Endpoint
- 1.2 Parâmetros de entrada
- 1.3 Exemplo request
- 1.4 Descrição dos objetos e atributos de retorno - Sucesso
- 1.5 Retorno da API - Sucesso
- 1.6 Retorno da API - Falha
2 Método "extratoPdf"
- 2.1 Endpoint
- 2.2 Parâmetros de entrada
- 2.3 Exemplo request:
- 2.4 Descrição dos objetos e atributos de retorno - sucesso
- 2.5 Retorno da API- Sucesso
- 2.6 Retorno da API - Falha

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

Método "extrato"

Este método é obrigatório;
Atente-se aos critérios de preenchimento;
Atente-se as mensagens de retorno para cada HTTPS Status Code;

Endpoint

Endpoint	Método	Header Content-Type	Descrição

Endpoint	Método	Header Content-Type	Descrição
/extratoUtilizacao/extrato Atenção O endpoint obrigatoriamente deve terminar com “/extrato”.	POST	application/json	Endpoint para listar os registros de utilização relacionadas ao localizador (chaveUnica)

Parâmetros de entrada

Serão enviados no HEADER os headers estáticos definidos ao configurar a integração, combinado com os tokens retornados pela configuração de autorização da integração (caso seja vinculada) e os headers de segurança retornado no login do beneficiário.

Serão enviados no BODY os seguintes parâmetros:

Parâmetro	Obrigatório	Tipo	Descrição

Parâmetro	Obrigatório	Tipo	Descrição
integracao	M	Objeto
chaveUnica	M	String
dataInicial	M	String	Data inicial do periodo desejado.
dataFinal	M	String	Data final do periodo. desejado.

Exemplo request

url: 
https://www.operadoradesaude.com.br/mobilesaude/extratoUtilizacao/extrato

Body:
{
  "integracao": {
        "xpto": "voluptatibus",
        "xyz": "quibusdam",
        "abcdef": 9288701
      },
  "chaveUnica": "string",
  "dataInicial": "YYYY-MM-DD",
  "dataFinal": "YYYY-MM-DD"
}

Descrição dos objetos e atributos de retorno - Sucesso

Está indicado abaixo a estrutura de retorno do método. Esse método deve obedecer as regras indicadas no objeto principal e em seus desdobramentos.

Objeto principal

Atributo	Critério	Tipo	Descrição	Regra de preenchimento

Atributo	Critério	Tipo	Descrição	Regra de preenchimento
alerta	OP	String	Informativo a ser exibido para o cliente sobre os dados apresentados a baixo.	Texto livre.
dataInicioPeriodoApuracao	M	String	Data de inicio da apuração aplicada pelo webservice do cliente.	Formato: YYYY-MM-DD
dataFimPeriodoApuracao	M	String	Data de fim da apuração aplicada pelo webservice do cliente.	Formato: YYYY-MM-DD
extrato	M	Array de objetos do tipo “detalheExtrado"	Retornar um array de objetos “detalheExtrato“.

Objeto detalhe extrato

Atributo	Critério	Tipo	Descrição	Regra de preenchimento

Atributo	Critério	Tipo	Descrição	Regra de preenchimento
chaveUnica	M	String	Chave de identificação do usuario.
codigoProcedimento	M	String	Código do procedimento a ser exibido no extrato	Formato: Texto livre.
dataAtendimento	M	String	Data de execução do serviço / atendimento	Formato: YYYY-MM-DD
descricaoProcedimento	M	String	Descrição do procedimento a ser exibido	Formato: Texto livre.
descricaoTipoServico	M	String	Descrição do tipo de serviço realizado, exemplo: Consultas, Exames/Terapias, Internação, Odontologia, outras despesas, entre outras. Assim como o atributo codigoTipoServico, servirá como agrupador para apresentação de subtotais exigidos pela RN 389.	Formato: Texto livre. Recomenda-se observância à RN 329
idContrato	M	String	Numero do contrato na qual o cliente esta vinculado
idExecutante	M	String	Código de identificação do prestador executante no seu sistema.	Formato: ASCII (nao permite especiais).
idTipoServico	M	String	Código do tipo de serviço realizado. O código de serviços será utilizado para agrupar os procedimentos e apresentar os subtotais exigidos pela RN 389	Formato: ASCII (nao permite especiais). Recomenda-se observância à RN 329
idTipoUsuario	M	String	Informe o tipo de usuário	Conteúdo válido: T = Titular D = Dependente A = Agregado Apenas maiúsculos.
localAtendimento	M	String	Indique o local no qual foi realizado o atendimento	Formato: Texto livre
nomeBeneficiario	M	String	Nome do beneficiário que aparecerá no extrato	Formato: Texto livre.
nomeExecutante	M	String	Nome do prestador executante.	Formato: Texto livre.
numeroGuia	M	String	numero da guia de registro do serviço/atendimento prestado.	Formato: Texto livre
quantidade	M	Numerico	Quantidade executada.	Numérico
valorServico	M	Numerico	Indique o valor individualizado do serviço. Poderá definir através da configuração da funcionalidade se deseja exibir o valor por grupo/ individualmente ou apenas o total. (RN 389 permite esse comportamento).	Formato: Numérico. Caso não tenha valor a ser exibido deve informar o valor zerado. Caso não queria exibir deve ajustar a configuração da funcionalidade para este comportamento.

Retorno da API - Sucesso

{
  "alerta": "Dica: Extrato de utilização se refere aos serviços médicos realizados em tempo real. Os valores informados se referem aos custos da operadora.",
  "dataInicioPeriodoApuracao": "2021-05-01",
  "dataFimPeriodoApuracao": "2021-05-15",
  "extrato": [
    {
      "idContrato": "99991",
      "chaveUnica": "10102",
      "nomeBeneficiario": "Derlandy Belchior",
      "idTipoUsuario": "T",
      "codigoProcedimento": "10101012",
      "descricaoProcedimento": "Consulta eletiva em consultório",
      "numeroGuia": "817191203-1019",
      "dataAtendimento": "2019-03-01",
      "idExecutante": "001",
      "nomeExecutante": "Dr. Elias Lovato Neto",
      "idTipoServico": "1",
      "descricaoTipoServico": "Consulta",
      "quantidade": 6.5,
      "valorServico": 553.7,
      "localAtendimento": "Laboratório Pretti Vitória"
    },
    {
      "idContrato": "99991",
      "chaveUnica": "10102",
      "nomeBeneficiario": "Derlandy Belchior",
      "idTipoUsuario": "T",
      "codigoProcedimento": "10101012",
      "descricaoProcedimento": "Consulta eletiva em consultório",
      "numeroGuia": "817191203-1019",
      "dataAtendimento": "2019-03-01",
      "idExecutante": "001",
      "nomeExecutante": "Dr. Elias Lovato Neto",
      "idTipoServico": "1",
      "descricaoTipoServico": "Consulta",
      "quantidade": 6.5,
      "valorServico": 553.7,
      "localAtendimento": "Laboratório Pretti Vitória"
    }
  ]
}

Retorno da API - Falha

Método "extratoPdf"

Este método irá retornar o pdf do extrato de Utilização referente à competência selecionada pelo beneficiário. Assim, o atendente de chat poderá de forma rápida enviar o PDF do extrato solicitado pelo beneficiário.

Prioriza-se a URL em relação ao base64
O método construído por sua empresa deverá validar se existem lançamentos na competência selecionada.
Será adicionado ao corpo da requisição as informações enviadas no atributo integracao e chaveUnica.

Endpoint

Endpoint	Método	Header Content-Type	Descrição

Endpoint	Método	Header Content-Type	Descrição
http://exemplo.com/ extratPdf	POST	application/json

Parâmetros de entrada

Serão enviados no HEADER os headers estáticos definidos ao configurar a integração, combinado com os tokens retornados pela configuração de autorização da integração (caso seja vinculada) e os headers de segurança retornado no login do beneficiário.

Serão enviados no BODY os seguintes parâmetros:

Parâmetro	Obrigatório	Tipo	Descrição

Parâmetro	Obrigatório	Tipo	Descrição
integracao	M	Objeto
chaveUnica	M	String
dataInicial	M	String	Data inicial do periodo desejado.
dataFinal	M	String	Data final do periodo. desejado.

Exemplo request:

url: 
https://www.operadoradesaude.com.br/mobilesaude/utilizacao/extratoPdf

Body:
{
  "integracao": {
    "xpto": "voluptatibus",
    "xyz": "quibusdam",
    "abcdef": 9288701
  },
  "chaveUnica": "101012",
  "dataInicial": "YYYY-MM-DD",
  "dataFinal": "YYYY-MM-DD"
}

Descrição dos objetos e atributos de retorno - sucesso

Está indicado abaixo a estrutura de retorno do método. Esse método deve obedecer as regras indicadas no objeto principal e em seus desdobramentos.

Objeto principal

Atributo	Critério	Tipo	Descrição	Regra de preenchimento

Atributo	Critério	Tipo	Descrição	Regra de preenchimento
url	C	String	url do documento em .pdf	Formato: texto livre Obrigatório quando “base64" não for preenchido.
base64	C	String	base64 do documento em .pdf	Formato: texto livre regra: Obrigatório quando “url" não for preenchido.

Método "extrato"

Endpoint

Parâmetros de entrada

Exemplo request

Descrição dos objetos e atributos de retorno - Sucesso

Retorno da API - Sucesso

Retorno da API - Falha

Método "extratoPdf"

Endpoint

Parâmetros de entrada

Exemplo request:

Descrição dos objetos e atributos de retorno - sucesso

Retorno da API- Sucesso

Retorno da API - Falha