Ir para o final dos metadados
Ir para o início dos metadados

Você está vendo a versão antiga da página. Ver a versão atual.

Comparar com o atual Ver Histórico da Página

« Anterior Versão 4 Atual »

Índice

Telas:

Screenshot 2024-11-05 at 09.25.54.png

Descrição:

Retorna uma lista dos períodos liberados para consulta ao demonstrativo de pagamento.

Regas de negócio

  • O aplicativo irá enviar para este webservice o conteúdo dos campos chaveUnica e integração os campos chave_cooperado (código do cooperado no seu sistema) e numero_cr (número de inscrição no concelho regional), devem ser retornados dentro do objeto de integração no payload de login.

  • Deve retornar uma lista com as competências e períodos de pagamento ao cooperado. A lista de períodos deve ser ordenada em ordem cronológica decrescente. Recomendamos retornar no máximo os últimos 12 meses, para não sobrecarregar a requisição;

Considera que os dados necessários para identificação do cooperado são: chaveUnica e integração. Envie no objeto integração os dados que você precisa para reconhecer o seu cooperado, esse conjunto de dados: chaveUnica + integração serão enviados em todas as requisições para seu sistema.

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

Orientações

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.

Critérios de preenchimento

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

Objetos e atributos de retorno

Os atributos devem seguir exatamente os mesmos nomes indicados nesta documentação, caso contrário, serão rejeitados pelo validador de integração.

Exemplo do atributo “contratos”:

  • Contrato

  • contrato

  • Contratos

  • contratos (concordo)

Método de listaPeriodos

Endpoint

Endpoint

Método

Header Content-Type

Descrição

http://exemplo.com/ listaPeriodos

POST

application/json

Retorna uma lista dos períodos liberados para consulta ao demonstrativo de pagamento.

Parâmetros de entrada

Atributo

Obrigatoriedade

Tipo

Descrição

chaveUnica

M

String

Chave de identificação do usuário retornada no login

integracao

M

Objeto

nó integração retornado no login do beneficiário

contrato

C

String

Contrato selecionado

Atenção

O atributo contrato será enviado quando o parâmetro: utilizaSelecaoContrato estiver ativo.

Objeto contrato

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

numeroContrato

M

String

Chave de identificação do controlado selecionado.

Enviado quando o parâmetro utilizaSelecaoContrato estiver ativo.

Exemplo request

url: 
https://www.operadoradesaude.com.br/mobilesaude/listaPeriodos

Body:
{
  "chaveUnica": "<chaveUnica>",
  "integracao": "{objeto}"
}

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

Está indicado abaixo a estrutura de retorno do seu método login. 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

competencias

M

Array de objetos”competencia”

Retorna um array de objetos “competencia”

Deve retornar um array de objetos

alerta

OP

String

Texto livre

Caso queira enviar um alerta para os cooperados no ato da apresentação dos periodos, descreva aqui.

Objeto competencia

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

titulo

M

Number

Titulo do registro

subtitulo

M

Number

Titulo do registro

valorTotal

M

Number

Informe o valor total da competencia.

periodos

M

Array

Array de objetos do tipo "periodo"

Retorna uma lista de objetos com a estrutura “periodo“. Essa estrutura define os períodos de pagamento dentro de uma competência. Se a sua operadora realiza apenas um pagamento por competência, essa estrutura terá apenas um registro com a data do pagamento. Se a sua operadora realiza mais de um pagamento na competência, retorne um registro para cada uma das datas de pagamento.

Objeto periodo

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

descricao

M

String

Id de banco de dados do título no seu sistema interno.

Somente números inteiros (Não podem existir letras, espaços em branco, ou pontos decimais).

Número único. Não pode ser repetido.

valor

M

Number

Informe o valor total do periodo

dataPagamento

M

String

Informe a data de pagamento deste período. Essa informação será apresentada ao cooperado na tela de Períodos.

Formato: YYYY-MM-DD

chavePagamento

M

String

Código do título no seu sistema interno, exemplo “MS00579”.

Formato: Texto livre.

Utilize este campo para montar a chave que irá identificar o período

Deve ser um identificador único. Não pode ser repetido.

Exemplo retorno API - sucesso

{
  "alerta": "",
  "competencias": [
    {
      "titulo": 2024 - Junho,
      "subtitulo": "",
      "valorTotal": 20003.96,
      "periodos": [
        {
          "descricao": "Segunda quinzena",
          "dataPagamento": "2024-06-01",
          "valor": 11003.01,
          "chavePagamento": "55555555:2024-06-01:101010"
        },
        {
          "descricao": "Primeira quinzena",
          "dataPagamento": "2024-06-01",
          "valor": 9000.95,
          "chavePagamento": "55555555:2024-06-01:101010"
        }
      ]
    },
    {
      "titulo": "Clinica Xyz",
      "subitulo": "Contrato: 1202100012",
      "valorTotal": 19150.5,
      "periodos": [
        {
          "descricao": "Segunda quinzena",
          "dataPagamento": "2024-05-01",
          "valor": 10150,
          "chavePagamento": "55555555:2024-05-01:101010"
        },
        {
          "descricao": "Primeira quinzena",
          "dataPagamento": "2024-05-01",
          "valor": 9000.95,
          "chavePagamento": "55555555:2024-05-01:101010"
        }
      ]
    },
    {
      "ano": 2024,
      "mes": 3,
      "valorTotal": 20003.96,
      "periodos": [
        {
          "descricao": "Segunda quinzena",
          "dataPagamento": "2024-04-01",
          "valor": 11003.01,
          "chavePagamento": "55555555:2024-04-01:101010"
        },
        {
          "descricao": "Primeira quinzena",
          "dataPagamento": "2024-04-01",
          "valor": 9000.95,
          "chavePagamento": "55555555:2024-04-01:101010"
        }
      ]
    }
  ]
}

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

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

  • Atente-se as mensagens de retorno para cada HTTPS Status Code;

Objetos e atributos de retorno

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

mensagem

M

String

mensagem para ser exibida para o cliente

 texto livre

Exemplo retorno API - falha

{
  "mensagem": "Não foi possível obter os detalhes deste débito. Por favor, entre em contato com suporte."
}

  • Sem rótulos