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 - Sucesso com Extrato vazio
- 1.7 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;

IMPORTANTE

Os aplicativos e plataformas web refletem os dados conforme são consumidos diretamente da API. Caso haja necessidade de ordenar ou organizar as informações seguindo regras específicas da operadora, essas configurações devem ser realizadas diretamente na API responsável pelo fornecimento dos dados.

Endpoint

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

Endpoint	Método	Header Content-Type	Descrição
/extratoUtilizacao/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 - Sucesso com Extrato vazio

{
  "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": []
}

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:

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.

4: API para Extrato de Utilização

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 - Sucesso com Extrato vazio

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