Caso sua empresa deseje exibir informações de coparticipação do beneficiário e de seu grupo familiar, esta API deverá ser implementada.

Índice

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

Importante

Aviso

Nas aplicações da Mobile Saúde (Apps e Web) o valor total da coparticiação e do serviço é calculado através de:

Total Coparticipação: quantidade x valorCoparticipacao

Total Serviço: quantidade x valorServico

Ou seja ao informar os campos valorCoparticipacao e valorServico se faz necessário dividir o valor de coparticipação e o valor de serviço pela quantidade apresentada, para que posteriormente seja multiplicado pelo nossos apps e frontend web.

Método "extrato"

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

Nota

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

/extratoCoparticipacao/extrato

Nota

Atenção

O endpoint obrigatoriamente deve terminar com “/extrato”.

POST

application/json

Endpoint para listar os registros de coparticipaçã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
integracao	M	Objeto
chaveUnica	M	String
dataInicial	M	String	Data inicial do periodo desejado.
dataFinal	M	String	Data final do periodo. desejado.

Exemplo request

Bloco de código

language	json

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

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

...

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
observacao	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

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

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

idContrato

M

String

Numero do contrato na qual o cliente esta vinculado.

descricaoContrato

M

String

Nome do contrato que aparecerá no extrato.

dataInicioVigenciaContrato

M

String

Data de inicio da vigencia do contrato que aparecerá no extrato.

chaveUnica

M

String

Chave de identificação do usuario.

nomeBeneficiario

M

String

Nome do beneficiário que aparecerá no extrato

Formato: Texto livre.

idTipoUsuario

M

String

Informe o tipo de usuário

Conteúdo válido:
T = Titular
D = Dependente
A = Agregado
Apenas maiúsculos.

codigoProcedimento

M

String

Código do procedimento a ser exibido no extrato

Formato: Texto livre.

descricaoProcedimento

M

String

Descrição do procedimento a ser exibido

Formato: Texto livre.

numeroGuia

M

String

numero da guia de registro do serviço/atendimento prestado.

Formato: Texto livre

dataAtendimento

M

String

Data de execução do serviço / atendimento

Formato: YYYY-MM-DD

idExecutante

M

String

Código de identificação do prestador executante no seu sistema.

Formato: ASCII (nao permite especiais).

nomeExecutante

M

String

Nome do prestador executante.

Formato: Texto livre.

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

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

quantidade

M

Numerico

Quantidade executada.

Numérico

valorServico

M

Numerico

Indique o valor individualizado (unitário) 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.

Informações
Informe o valor unitário. O valor será multiplicado pelo atributo quantidade.

valorCoparticipacao

M

Numerico

Indique o valor da coparticipação 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.

Informações
Informe o valor unitário. O valor será multiplicado pelo atributo quantidade.

localAtendimento

M

String

Indique o local no qual foi realizado o atendimento

Formato: Texto livre

Retorno da API - Sucesso

Bloco de código

language	json

{
  "observacao": "Em conformidade com a legislação, o titular pode visualizar todos os serviços realizados por seus dependentes. No entanto, a especificação completa de alguns serviços e procedimentos estão protegidos visando a privacidade de seus realizadores.",
  "dataInicioPeriodoApuracao": "2021-05-01",
  "dataFimPeriodoApuracao": "2021-05-15",
  "extrato": [
    {
      "idContrato": "99991",
      "descricaoContrato":"Plano Gold Família",
      "dataInicioVigenciaContrato":"2019-01-01",
      "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",
      "descricaoContrato":"Plano Gold Família",
      "dataInicioVigenciaContrato":"2019-01-01",
      "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

Aviso
Atente-se as mensagens de retorno para cada HTTPS Status Code; Siga as instruções de Descrição dos objetos e atributos de retorno - falha;

Método "extratoPdf"

Este método aplica-se apenas para a funcionalidade de CHAT através de widget.

Nota

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

...

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

http://exemplo.com/ extratPdf

Nota

Atenção

O endpoint obrigatoriamente deve terminar com “/extratoPdf”.

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
integracao	M	Objeto
chaveUnica	M	String
dataInicial	M	String	Data inicial do periodo desejado.
dataFinal	M	String	Data final do periodo. desejado.

Exemplo request:

Bloco de código

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

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

...

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
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.

Retorno da API- Sucesso

Bloco de código
{ "url": "https://ms-publico.s3-sa-east-1.amazonaws.com/mockups/extrato/extratoCoparticipacaoModelo.pdf", "base64": null }

...

Aviso
Atente-se as mensagens de retorno para cada HTTPS Status Code; Siga as instruções de Descrição dos objetos e atributos de retorno - falha;

Version	Versão antiga 11	Nova versão Atual
Alterações feitas por	Jean Schulz	Ranniêr Reis
Gravado em	ago. 11, 2023	set. 19, 2024

Comparação de Páginas

Versões comparadas

Chave

Importante

Método "extrato"

Endpoint

Parâmetros de entrada

Exemplo request

Retorno da API - Sucesso

Retorno da API - Falha

Método "extratoPdf"

Endpoint

Parâmetros de entrada

Exemplo request:

Retorno da API- Sucesso