2.1 - Lista débitos

Índice

1 Índice
2 Orientações
- 2.1 Parâmetros de entrada
3 Critérios de preenchimento
4 Objetos e atributos de retorno
5 Método de listaDebitos
- 5.1 Endpoint
- 5.2 Parâmetros de entrada
- 5.3 Exemplo request
- 5.4 Descrição dos objetos e atributos de retorno - Sucesso
  - 5.4.1 Exemplo retorno API - sucesso
  - 5.4.2 Descrição dos objetos e atributos de retorno - falha
  - 5.4.3 Exemplo retorno API - falha

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",
                    "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
                }
            ]
        }
    ]
}

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

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