5: API para Extrato de Coparticipação

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

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
/extratoCoparticipacao/extrato 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

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"
}

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

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 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.
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.
localAtendimento	M	String	Indique o local no qual foi realizado o atendimento	Formato: Texto livre

Retorno da API - Sucesso

{
  "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

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 é opcional;
Atente-se aos critérios de preenchimento;
Atente-se as mensagens de retorno para cada HTTPS Status Code;

Este método irá retornar o pdf do extrato de Coparticipação referente à competência selecionada 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.