Índice
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”:
ContratocontratoContratoscontratos
Método de listaPeriodos
Atente-se as orientações fornecidas pela Mobile Saúde;
Atente-se aos critérios de preenchimento;
Atente-se aos critérios de objetos e atributos de retorno;
Atente-se as mensagens de retorno para cada HTTPS Status Code;
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."
}