2.2 - Detalhes debito

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

 

Endpoint

Endpoint

Método

Header Content-Type

Descrição

Endpoint

Método

Header Content-Type

Descrição

http://exemplo.com/ detalheDebito

POST

application/json

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

Parâmetros de entrada

Parâmetro

Obrigatório

Tipo

Descrição

Parâmetro

Obrigatório

Tipo

Descrição

idTitulo

M

Number

Id de banco de dados da título no seu sistema interno. O aplicativo irá enviar a mesma informação que recebeu do atributo idTitulo do método listaDebito

codigoTitulo

M

String

Código do titulo no seu sistema interno. O aplicativo irá enviar a mesma informação que recebeu do atributo codigoTitulo do método listaDebito

chaveUnica

M

String

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

integracao

OP

Objeto

Nó integração retornado no login do usário

 

Exemplo request

url: https://www.operadoradesaude.com.br/mobilesaude/detalheDebito Body: { "chaveUnica" : "101012", "integracao": { "xpto": "voluptatibus", "xyz": "quibusdam", "abcdef": 9288701 }, "idTitulo": 579, "codigoTitulo": "MS00579", }

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

numeroContrato

M

String

numero do contrato vinculado a este debito

 

idTitulo

M

Number

id do debito no seu sistema

Exemplo: 579

codigoTitulo

M

String

codigo do titulo no seu sistema

texto livre: “MS00579"

alerta

OP

Object

Objeto do tipo "alerta"

Informativo a ser exibido no card de alerta da tela. Consulte o layout.

valor

M

Float

Valor do título liquido do título, sem multas ou juros.

Numérico, 2 posições decimais. Indicador decimal = PONTO (9999999.99)

dataVencimento

M

String

Data do vencimento do título.

Formato: YYYY-MM-DD

dataPagamento

C

String

Data de pagamento do título.

Formato: Formato: YYYY-MM-DD

Se o titulo já foi pago, enviar a data do pagamento.

Obrigatório quando a propriedade situação for igual a "B".

cedenteNome

M

String

Nome do cedente.

Formato: Texto Livre.

observacao

OP

String

Informe um texto de observação para ser apresentado na tela de detalhes do boleto. Este texto será apresentado abaixo da linha digitavel.

Formato: Texto livre

situacao

M

Objeto

Objeto que indica a situação de pagamento atual do boleto.

Obrigatório o preenchimento conforme objeto "situacao" descrito posteriormente.

Boleto

C

objeto

Objeto do tipo "boleto" segue a baixo na documentacao

Obrigatorio quando tipo de pagamento = “B" boleto

tipoCobranca

M

objeto

Objeto que indica o tipo de cobranca do boleto.

Obrigatório o preenchimento conforme objeto "tipoCobranca" descrito posteriormente.

comprovantePagamento

M

objeto

Objeto do tipo “botao"

 As regras de preenchimento deste atributo são referentes ao Objeto botao

resumoCobranca

M

objeto

Objeto do tipo “botao"

  As regras de preenchimento deste atributo são referentes ao Objeto botao

boletoPdf

M

objeto

Objeto do tipo “botao"

  As regras de preenchimento deste atributo são referentes ao Objeto botao

atualizacaoValor

OP

array de objeto “atualizacaoValor”

Array de objeto com a estrutura “atualizacaoValor”

 

descricao

M

String

Texto que será exibido na tela de título do detalhe do débito.

Recomendamos que utilize o mesmo conteúdo do atributo descricao do método listaDebitos.

Utilize este campo para adicionar uma descrição do título nos detalhes dos débitos. Utilize conteúdos como “coparticipação”, “mensalidade”, “renegociação” ou qualquer outro conteúdo. Ele será exibido no título da tela de detalhes do débito.

 

Objeto alerta

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

icone

OP

String

icone a ser utilizado no card de alerta. Verifique a lista de icones disponiveis pela mobile.

 

mensagem

M

String

Informe a mensagem a ser exibida no card de alerta. Consulte o layout

texto livre

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

Importante: A linha digitável só será exibida caso o id seja “B”. Demais tipos de cobrança não exibem a linha digitável.

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

 

Objeto botao

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

ativo

M

Boolean

indica se o botão deve estar ativo para o usuario

true or false

label

M

String

O nome que vc deseja exibir para o usuario.

Exemplos:
”resumo de cobrança",
”Boleto em PDF"

 

Objeto boleto

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

linhaDigitavel

C

String

Código completo da linha digitável do boleto.

Importante: esse é o método que vai apresentar o boleto registrado no banco em tela.

Caso você não tenha cobrança registrada, deve-se utilizar o método de Gerar Boleto Sob Demanda.

Obrigatório quando o PARÂMETRO DE CONFIGURAÇÃO DE FUNCIONALIDADE"solicitaGeracaoDeBoleto" = false.

 

Importante:

A linha digitável só será exibida caso o atributo id do objeto tipoCobranca seja “B” = Boleto

Recomendamos que esse atributo seja informado sempre que o boleto esteja em situação diferente de BAIXADO (B).

 

Obs: solicitaGeracaoDeBoleto é um parâmetro de configuração da funcionalidade, configurável pelo configurador púbico na feature de Boletos / aba PARAMETROS.

solicitaConfirmacao

M

Boolean

 

 

textoConfirmacao

OP

String

mensagem apresentada no momento de solicitar a confirmação de geracao de boleto de cobranca

Texto livre

 

Objeto atualizacaovalor

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

Atributo

Critério

Tipo

Descrição

Regra de preenchimento

informacoes

OP

String

 

texto livre

valorOriginal

M

String

valor da fatura antes do vencimento

Numérico, 2 posições decimais. Indicador decimal = PONTO (9999999.99)

vencimentoOriginal

M

String

Data de vencimento da fatura

Formato: Formato: YYYY-MM-DD

 

Exemplo retorno API - sucesso

{ "numeroContrato": "00100200300400500607", "alerta": { "icone": "icon_boleto_calendar", "cor":"#FF0000", "mensagem":"Sua cobrança está programada para cartão de crédito. Caso queira pagar agora, basta clicar para gerar um boleto." }, "idTitulo": 579, "codigoTitulo": "MS00579", "valor": 254.00, "dataVencimento": "2019-08-24", "dataPagamento": null, "cedenteNome": "Nome do cedente", "observacao": "Voluptas tempore beatae sequi", "descricao": "Mensalidade", "situacao": { "id": "A", "descricao": "Vencido", "cor": "#FF0000" }, "tipoCobranca": { "id": "B", "descricao": "Boleto", "cor": "#fff" }, "boleto": { "linhaDigitavel": "0012345678900123456700050543211000000000123456", "solicitaConfirmacao": true, "textoConfirmacao": "Ao gerar o código de barras, a modalidade de cobrança será atualizada. Deseja confirmar ?" }, "comprovantePagamento": { "ativo": true, "label": "Comprovante de pagamento" }, "resumoCobranca": { "ativo": true, "label": "Resumo de cobrança" }, "boletoPdf": { "ativo": true, "label": "Salvar boleto (PDF)" }, "atualizacaoValor": { "informacoes": "Minima et sit iste dolores. Dolore animi libero vel temporibus voluptas quaerat a provident. In tempora eos asperiores fugit asperiores. Ab et autem quam libero consequuntur.", "valorOriginal": 809.00, "vencimentoOriginal": "2019-08-31" } }

 

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

 

 

Ícones disponíveis (.png)

icon_boleto_calendar

icon_boleto_card

icon_boleto_check

icon_boleto_exclamation

Icon_boleto_exclude

icon_boleto_money

icon_boleto_notification

icon_boleto_star