2.1 - Lista débitos
Índice
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
Método de listaDebitos
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;
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 |
|---|---|---|---|
exemplo.com listaDebitos | POST | application/json | Endpoint para listar débitos relacionados ao localizador (chaveUnica) |
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 |
Exemplo request
url:
https://www.operadoradesaude.com.br/mobilesaude/listaDebitos
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 |
|---|---|---|---|---|
contratos | M | Array de objetos”contrato” | Retorna um array de objetos “contratos” | Deve retornar um array de objetos |
Objeto contratos
Atributo | Critério | Tipo | Descrição | Regra de preenchimento |
|---|---|---|---|---|
numeroContrato | M | String | Número que identifica a qual contrato esse débito está vinculado | Texto livre |
debitos | M | Array | Array de objetos do tipo "debito" | Precisa ser preenchido com pelo menos um item |
Objeto debitos
Atributo | Critério | Tipo | Descrição | Regra de preenchimento |
|---|---|---|---|---|
idTitulo | M | Number | 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. |
codigoTitulo | M | String | Código do título no seu sistema interno, exemplo “MS00579”. | Formato: Texto livre. Número único. Não pode ser repetido. |
dataEmissao | M | String | Data de emissão do débito. | Formato: YYYY-MM-DD |
dataVencimento | M | String | Data de vencimento do débito. | Formato: YYYY-MM-DD |
dataVencimentoAtualizado | OP | String | Data de vencimento atualizada do débito. | Formato: YYYY-MM-DD |
situacao | M | objeto | Objeto que indica a situação de pagamento atual do boleto. | Obrigatório o preenchimento conforme objeto "situacao" descrito posteriormente. |
tipoCobranca | M | objeto | Objeto que indica o tipo de cobranca do boleto. | Obrigatório o preenchimento conforme objeto "tipoCobranca" descrito posteriormente. |
valor | M | Float | Valor total do boleto (Numérico, 2 posições decimais) | Numérico, 2 posições decimais. Indicador decimal = PONTO (9999999.99) |
valorAtualizado | OP | Float | Valor total atualizado do boleto (Numérico, 2 posições decimais) | Numérico, 2 posições decimais. Indicador decimal = PONTO (9999999.99) |
descricao | OP | String | Utilize este campo para adicionar uma descrição do título na lista de boletos. Este campo é ideal para identificar na listagem um título de coparticipação, titulo de mensalidade ou de renegociação. | Formato: Texto livre. |
faturaDigital | OP | Boolean | Se sua empresa deseja disponibilizar a fatura em formato digital atribua o valor true | true ou false |
debitoAutomatico | OP | Boolean |
| true or false |
Objeto situacao
Atributo | Critério | Tipo | Descrição | Regra de preenchimento |
|---|---|---|---|---|
id | M | String | Código ou ID que represente o status do débito no seus sistema. | P = A Vencer (em aberto porém ainda não está vencido). A = Atrasado (em aberto, porém já vencido). B = Baixado (já foi pago). |
descricao | M | String | Descrição da situação do débito | “A vencer”, “Atrasado”, “Baixado” |
cor | M | String | cor da label a ser exibida. | Hexadecimal. com o #. da cor que deseja que seja usada para representar a situação do débito. Ex.: |
Objeto tipoCobranca
Atributo | Critério | Tipo | Descrição | Regra de preenchimento |
|---|---|---|---|---|
id | M | String | Indique o tipo de cobrança para seu documento de cobrança, conforme padrão definido do layout (regra de preenchimento) | C = Consignação / desconto em folha. B = Boleto. D = Débito em conta. |
descricao | M | String | Descrição da situação do débito |
|
cor | M | String | cor da label a ser exibida. | Hexadecimal. com o #. da cor que deseja que seja usada para representar o tipo de cobranca do débito. Ex.: |
Exemplo retorno API - sucesso
{
"contratos": [
{
"numeroContrato": "00100200300400500609",
"debitos": [
{
"idTitulo": 579,
"codigoTitulo": "MS00579",
"dataEmissao": "2018-09-01",
"dataVencimento": "2018-09-05",
"dataVencimentoAtualizado" : "2024-02-01",
"situacao": {
"id": "A",
"descricao": "Vencido",
"cor": "#FF0000"
},
"tipoCobranca": {
"id": "B",
"descricao": "Boleto",
"cor": "#fff"
},
"valor": 254,
"valorAtualizado" : 350.00,
"descricao": "Mensalidade",
"faturaDigital": false,
"debitoAutomatico": false
},
{
"idTitulo": 572,
"codigoTitulo": "MS00572",
"dataEmissao": "2018-09-01",
"dataVencimento": "2018-09-05",
"dataVencimentoAtualizado" : "2024-02-01",
"situacao": {
"id": "B",
"descricao": "Paga",
"cor": "#5BCE5B"
},
"tipoCobranca": {
"id": "B",
"descricao": "Boleto",
"cor": "#fff"
},
"valor": 254,
"valorAtualizado" : 350.00,
"descricao": "Mensalidade",
"faturaDigital": false,
"debitoAutomatico": false
},
{
"idTitulo": 573,
"codigoTitulo": "MS00573",
"dataEmissao": "2018-09-01",
"dataVencimento": "2018-09-05",
"dataVencimentoAtualizado" : "2024-02-01",
"situacao": {
"id": "P",
"descricao": "A pagar",
"cor": "#FFBB02"
},
"tipoCobranca": {
"id": "B",
"descricao": "Boleto",
"cor": "#fff"
},
"valor": 54.44,
"valorAtualizado" : 350.00,
"descricao": "Coparticipação Especial",
"faturaDigital": false,
"debitoAutomatico": false
}
]
}
]
}
Exemplo retorno API - sucesso, sem débitos
{
"contratos": [
{
"numeroContrato": "00100200300400500609",
"debitos": [ ]
}
]
}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."
}
Related content
Mobile Saúde - Mosia Omnichannel