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

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

Endpoint

Endpoint

Método

Header Content-Type

Descrição

Endpoint

Método

Header Content-Type

Descrição

http://exemplo.com/ listaDebitos

POST

application/json

Endpoint para listar débitos relacionados ao localizador (chaveUnica)

Parâmetros de entrada

Atributo

Obrigatoriedade

Tipo

Descrição

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

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

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

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

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.: #FF0000

 

Objeto tipoCobranca

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

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.: #FF0000

 

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", "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 } ] }, { "numeroContrato": "00100200300400500608", "debitos": [ {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 } ] }, { "numeroContrato": "00100200300400500608", "idTitulo": 570, "codigoTitulo": "MS00570", "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": 254, "valorAtualizado" : 350.00, "descricao": "Mensalidade", "faturaDigital": false, "debitoAutomatico": false }, { "idTitulo": 571, "codigoTitulo": "MS00571", "dataEmissao": "2018-09-01", "dataVencimento": "2018-09-05", "dataVencimentoAtualizado" : "2024-02-01" "situacao": { "id": "A", "descricao": "Vencido", "cor": "#FF0000" }, "tipoCobranca": { "id": "D", "descricao": "Débito automático", "cor": "#fff" }, "valor": 24.5, "valorAtualizado" : 350.00, "descricao": "Coparticipação Especial", "faturaDigital": false, "debitoAutomatico": false } ] }, { "numeroContrato": "00100200300400500607", "debitos": [ { "idTitulo": 574, "codigoTitulo": "MS00574", "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": 12.9, "valorAtualizado" : 350.00, "descricao": "Coparticipação", "faturaDigital": false, "debitoAutomatico": false } ] } ] }

 

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

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