Extrato de boletos bancários

Transcrição

1 Layout de integração com webservices de clientes Extrato de boletos bancários Objetivo Este documento tem como objetivo orientar a construção de um webservices para apresentação do extrato de boletos bancários, o extrato da fatura e o comprovante de pagamento de títulos pagos. Necessidade Disponibilizar aos seus clientes extrato de boletos bancários que permita visualizar títulos em aberto (inclusive os atrasados) e os pagos. Os seus clientes poderão emitir o boleto e o extrato da fatura de títulos em aberto, ou emitir comprovantes de pagamento de títulos pagos. Solução Proposta A Mobile Saúde propõe um layout de integração para construção de um webservice que fornecerá dados necessários para emissão do boleto, do extrato e do comprovante de pagamento. Lista de métodos que serão descritos: lista_boletos: retorna uma lista de boletos para serem apresentados em tela detalhe_boleto: retorna os detalhes básicos do boleto para serem apresentados em tela boleto_pdf: retorna um arquivo PDF ou BASE64 do arquivo PDF do boleto completo. Este método será utilizado para apresentar o boleto completo para o usuário. extrato_fatura: retorna os dados para geração do extrato da fatura extrato_fatura_pdf: retorna um arquivo PDF ou BASE64 do arquivo PDF com o extrato do boleto. Este método substitui o método extrato_fatura, ou seja, se preferir criar este método não precisa criar o método extrato_fatura. Padrões de webservices Estamos familiarizados a trabalhar com webservice nos padrões REST e SOAP. Detalhamento dos serviços e das regras de negocio envolvidos Serviço: ws_boleto método: lista_boletos Descrição do método Este método irá retornar a lista de títulos do beneficiário. A quantidade de títulos retornados, o período e a regra deste retorno fica a critério da operadora. contato@ R. Agenor Amaro dos Santos, 785 sala 3 - Vitória-ES CEP

2 Este método deverá receber a identificação do beneficiário ; o Deverá avaliar se o beneficiário requisitante tem direitos para solicitar esta informação; o Deverá retornar uma lista de títulos ordenado da forma como deseja apresentar ao usuário;! A quantidade de títulos que será retornada é da sua escolha, mas recomendamos no máximo 12 meses ou todos os que estão em aberto, para não sobrecarregar a requisição; O método deverá retornar a linha digitável pronta, conforme regras de negocio da sua operadora. A Mobile Saúde não faz cálculo de linha digitável. Parâmetros de entrada chave_beneficiario String Sim Chave única do beneficiário no seu sistema de gestão. status Boolean Sim True = indica que a requisição foi bem sucedida False = Indica que a requisição foi mal sucedida motivo_critica String Não Quando o status for igual a False, envie nesta propriedade o motivo obrigatório quando o status igual a False boletos Array de Sim Retornar uma lista de objetos boleto (definição abaixo) objetos boleto alerta String Não Caso queira enviar um alerta para os beneficiário no ato da apresentação dos boletos, descreva aqui. Definição da estrutura boleto. titulo_codigo String Sim Código do título no seu sistema interno, exemplo REE titulo_id Int Não Id de banco de dados da título no seu sistema interno Observação importante: se o seu sistema exigir o id do título como chave para localizar o mesmo nos demais métodos, este campo deverá ser considerado obrigatório contrato_id Int Não Id do contrato do beneficiário. Este código pode ser útil quando o beneficiário está presente em mais de um contrato Observação importante: se o seu sistema exigir o id do contrato do beneficiário como chave para diferenciar os títulos do mesmo, este campo deverá considerado obrigatório data_emissao Date Sim Data de emissão do boleto Formato: yyyy-mm-dd data_vencimento Date Sim Data de vencimento do boleto Formato: yyyy-mm-dd contato@ R. Agenor Amaro dos Santos, 785 sala 3 - Vitória-ES CEP

3 situacao String Sim 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) tipo_cobranca String Sim C=Consignação / desconto em folha B=Boleto D=Débito em conta valor Float Sim Valor total do boleto método: detalhe_boleto Descrição do método Este método irá retornar o detalhamento do titulo selecionado pelo usuário O aplicativo irá enviar para este webservice o conteúdo dos campos titulo e titulo_codigo, titulo_id e contrato_id, retornados pelo método lista_boletos. O método deverá validar se a fatura existe Parâmetros de entrada titulo_codigo String Sim Código do titulo no seu sistema interno. O aplicativo irá enviar a mesma informação que recebeu no campo titulo_codigo do método lista_boleto titulo_id Int Não ID de banco de dados do titulo no seu sistema interno. O aplicativo irá enviar a mesma informação que recebeu no campo titulo_id do método lista_boleto contrato_id Int Não Id do contrato do beneficiário. O aplicativo irá enviar a mesma informação que recebeu no campo contrato_id do método lista_boleto Status Boolean Sim True = indica que a requisição foi bem sucedida False = Indica que a requisição não foi bem sucedida Motivo_critica String Não Quando o status for igual a Falso, envie nesta propriedade o motivo obrigatório quando o status igual a Falso detalhes Array de objetos detalhe Sim Retornar um objeto com a estrutura detalhe (definição abaixo). Cada elemento dentro deste array representa um boleto a cobrar do beneficiário e seu grupo familiar Alerta String Não Caso queira enviar um alerta para os beneficiário no ato da apresentação dos boletos, descreva aqui. Definição da estrutura detalhe. cedente_cnpj String Sim CNPJ do Cedente do boleto cedente_codigo String Sim Código do cedente do boleto contato@ R. Agenor Amaro dos Santos, 785 sala 3 - Vitória-ES CEP

4 cedente_nome String Sim Nome do cedente cedente_endereco String Não Endereço do cedente Observação importante: se o endereço do cedente estiver presente no boleto, este campo torna-se obrigatório cedente_complem String Não Complemento do endereço do cedente ento titular_contrato String Não Código do contrato do titular Observação importante: se essa informação for necessária na impressão do boleto ou do comprovante de pagamento, este campo torna-se obrigatório titular_cpf String Não CPF do titular Observação importante: se essa informação for necessária na impressão do boleto ou do comprovante de pagamento, este campo torna-se obrigatório titular_codigo String Não Código / Matrícula do titular Observação importante: se essa informação for necessária na impressão do boleto ou do comprovante de pagamento, este campo torna-se obrigatório titular_nome String Não Nome do titular Observação importante: se essa informação for necessária na impressão do boleto ou do comprovante de pagamento, este campo torna-se obrigatório codigo_carteira String Sim Código da carteira do boleto local_pagamento String Não Código do local de pagamento linha_digitavel String Não Código completo da linha digitável do boleto, sem pontos, espaços ou qualquer caractere especial Obrigatório quando o campo imprime_boleto for igual a S (sim). data_vencimento String Sim Data do vencimento do título data_pagamento String Não Se o titulo já foi pago, enviar a data do pagamento valor Double Sim Valor do título liquido do título, sem multas ou juros multa Double Não Valor da multa por atraso Observação importante: a obrigatoriedade depende da sua regra de negocio juro_dia Double Não Percentual de juros a ser cobrado por dia de atraso Observação importante: a obrigatoriedade depende da sua regra de negocio Imprime_boleto String Sim S = Sim, permite a geração do boleto N = Não. Não permite a geração do boleto Exemplos a serem considerados: contato@ R. Agenor Amaro dos Santos, 785 sala 3 - Vitória-ES CEP

5 1 - Se o tipo de cobrança for Débito em Conta e o titulo NÃO estiver vencido, não deve permitir gerar o boleto. Neste caso, envie N 2 Se o tipo de cobrança for Boleto, mas a situação do titulo for PAGO, não deve permitir gerar o boleto. Neste caso, envie N 3 Se o tipo de cobrança for Débito em Conta, a situação for Atrasado e já está vencido a 3 dias, libera para geração do Título. Neste caso, envie S Em resumo, o aplicativo irá permitir a geração do boleto toda vez que este campo vier com S. numero_nf String Não Número da nota fiscal vinculada ao título situacao String Sim 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) tipo_cobranca String Sim C=Consignação / desconto em folha B=Boleto D=Débito em conta instrucoes Array de objetos instrucao Não Retornar um objeto com a estrutura instrucao (definição abaixo). Cada elemento dentro deste array representa uma linha de instrução que será impressa no campo Instruções/Observações do boleto nosso_numero String Não Informação que deverá constar no campo Nosso Número do boleto. Definição da estrutura instrucao. instrucao String Sim texto da linha de observação, exemplo: Não Receber após 03/12/2015 método: boleto_pdf Descrição do método Este método irá retornar um campo BASE64 contendo o arquivo PDF do boleto completo. Observação importante: você pode optar por não desenvolver este método e ao invés disso, fornecer uma URL que recebe os mesmos parâmetros via GET ou via POST e retorna um arquivo PDF pronto para download. O aplicativo irá enviar para este webservice o conteúdo dos campos titulo e titulo_codigo, titulo_id e contrato_id, retornados pelo método lista_boletos. O método deverá validar se a fatura existe contato@ R. Agenor Amaro dos Santos, 785 sala 3 - Vitória-ES CEP

6 Parâmetros de entrada titulo_codigo String Sim Código do titulo no seu sistema interno. O aplicativo irá enviar a mesma informação que recebeu no campo titulo_codigo do método lista_boleto titulo_id Int Não ID de banco de dados do titulo no seu sistema interno. O aplicativo irá enviar a mesma informação que recebeu no campo titulo_id do método lista_boleto contrato_id Int Não Id do contrato do beneficiário. O aplicativo irá enviar a mesma informação que recebeu no campo contrato_id do método lista_boleto Status Boolean Sim True = indica que a requisição foi bem sucedida False = Indica que a requisição não foi bem sucedida Motivo_critica String Não Quando o status for igual a Falso, envie nesta propriedade o motivo obrigatório quando o status igual a Falso Boleto_base64 Base64 Sim Retorna conteúdo binário, tipo base64, do arquivo PDF do boleto. método: extrato_fatura Descrição do método Este método irá retornar a composição da cobrança vinculada ao título selecionado, separado por beneficiário, para que seja possível gerar o extrato que acompanha o boleto. Exemplos de serviços Mensalidade Coparticipação Taxa de adesão de novo dependente Segunda via de cartão e etc... O aplicativo irá enviar para este webservice o conteúdo dos campos titulo e titulo_codigo, titulo_id e contrato_id, retornados pelo método lista_boletos. O método deverá validar se a fatura existe O método deverá retornar os eventos por beneficiário Parâmetros de entrada titulo_codigo String Sim Código do titulo no seu sistema interno. O aplicativo irá enviar a mesma informação que recebeu no campo titulo_codigo do método lista_boleto titulo_id Int Não ID de banco de dados do titulo no seu sistema interno. O aplicativo irá enviar a mesma informação que recebeu no campo titulo_id do método lista_boleto contrato_id Int Não Id do contrato do usuário. O aplicativo irá enviar a mesma informação que contato@ R. Agenor Amaro dos Santos, 785 sala 3 - Vitória-ES CEP

7 recebeu no campo contrato_id do método lista_boleto status Boolean Sim True = indica que a requisição foi bem sucedida False = Indica que a requisição não foi bem sucedida motivo_critica String Não Quando o status for igual a False, envie nesta propriedade o motivo obrigatório quando o status igual a False detalhes Array de objetos extrato Sim Retornar um objeto com a estrutura extrato (definição abaixo). Cada objeto deste array contém a composição da cobrança de um beneficiário alerta String Não Caso queira enviar um alerta para os beneficiário no ato da apresentação dos boletos, descreva aqui. Definição da estrutura extrato. beneficiario_matri String Sim Matricula do beneficiário cula beneficiario_nome String Sim Nome do beneficiário grau_dependencia Strig Não Descrição do grau de dependência do beneficiário em relação ao titular composicao Array de objetos composicao Sim Se for o próprio titular, retornar Titular. Retornar um objeto com a estrutura composicao (definição abaixo). Definição da estrutura composicao. servico_codigo String Sim Código ou verba que identifica o serviço na composição da cobrança. Exemplos: 101 = mensalidade 102 = opcional remoção 103 = taxa de adesão de novo dependente 116 = coparticipação realizada em recurso próprio 117 = coparticipação realizada pelo cooperado 118 = coparticipação realizada na rede credenciada PJ servico_descricao String Sim Descrição do serviço quantidade Double Não Quantidade realizada valor Double Não Valor unitário do serviço método: extrato_fatura_pdf contato@ R. Agenor Amaro dos Santos, 785 sala 3 - Vitória-ES CEP

8 Este método irá retornar um campo BASE64 contendo o arquivo PDF com o extrato do boleto. Este método substitui o método extrato_fatura, ou seja, se preferir criar este método não precisa criar o método extrato_fatura. Observação importante: você pode optar por não desenvolver este método e ao invés disso, fornecer uma URL que recebe os mesmos parâmetros via GET ou via POST e retorna um arquivo PDF pronto para download. O aplicativo irá enviar para este webservice o conteúdo dos campos titulo e titulo_codigo, titulo_id e contrato_id, retornados pelo método lista_boletos. O método deverá validar se a fatura existe Parâmetros de entrada titulo_codigo String Sim Código do titulo no seu sistema interno. O aplicativo irá enviar a mesma informação que recebeu no campo titulo_codigo do método lista_boleto titulo_id Int Não ID de banco de dados do titulo no seu sistema interno. O aplicativo irá enviar a mesma informação que recebeu no campo titulo_id do método lista_boleto contrato_id Int Não Id do contrato do usuário. O aplicativo irá enviar a mesma informação que recebeu no campo contrato_id do método lista_boleto status Boolean Sim True = indica que a requisição foi bem sucedida False = Indica que a requisição não foi bem sucedida motivo_critica String Não Quando o status for igual a False, envie nesta propriedade o motivo obrigatório quando o status igual a False extrato_base64 Base64 Sim Retorna conteúdo binário, tipo base64, do arquivo PDF do extrato de cobrança contato@ R. Agenor Amaro dos Santos, 785 sala 3 - Vitória-ES CEP