Serviço externo padrão - Realiza renegociação
Este serviço realiza a renegociação de parcelas, permitindo informar as parcelas de origem, destino e dados para geração de título, que poderá ser feita pelo sistema externo ou pelo MentorWeb.
1. Parâmetros para chamada do serviço externo
| Parâmetro | Tipo de dado | Permite nulo? | Informações | |
|---|---|---|---|---|
| reneg | NÃO | Nesta Tag serão passadas várias informações referentes a renegociação. | ||
| dataRen | DATETIME | NÃO | Data da renegociação. | |
| observ | VARCHAR(4000) | NÃO | Observação da Renegociação. | |
| usuario | VARCHAR(255) | NÃO | login de usuário do mentorweb válido. | |
| honorario | NUMERIC(18,2) | NÃO | Valor de honorários. | |
| custaJudic | NUMERIC(18,2) | NÃO | Valor das custas judiciais. | |
| clausulaPen | NUMERIC(18,2) | NÃO | Valor da cláusula penal. | |
| descon | NUMERIC(18,2) | NÃO | Desconto concedido na renegociação. | |
| acresc | NUMERIC(18,2) | NÃO | Acréscimo cobrado na negociação. | |
| permiteRenegociadas | INT | NÃO | Permite renegociar parcelas já renegociadas, 1 para Permitir, 0 para negar. | |
| datbaixaParRen | VARCHAR(10) | NÃO | Informar: -DATAATU: Se informado vai utilizar a data atual na baixa; -DATAVEN: Se informado vai utilizar a data de vencimento da parcela na baixa. | |
| tipoBai | INT | NÃO | Informar qual o Código do tipo de baixa do MentorWeb que será utilizado para baixar as parcelas que estão sendo renegociadas. | |
| parcelaOri | Lista | NÃO | Nesta Tag serão passadas várias informações das parcelas de origem, descritas na tabela abaixo | |
| parId | INT | Não | Informar o Id da parcela de origem que será renegociada. | |
| periodoLet | DATE(dd/mm/aaaa) | SIM | O sistema vai receber esta informação e com base nesta data vai vincular o contrato financeiro a um período letivo com base nesta data. Se não for informado, será considerada a data atual | |
| resp | Lista | NÃO | Nesta Tag serão passadas várias informações do cadastro do responsável das parcelas geradas na renegociação. | |
| cpfResp | VARCHAR(20) | NÃO | Informar o CPF somente números | |
| nomeResp | VARCHAR(255) | NÃO | Informar o nome da pessoa. | |
| cepResp | CHAR(8) | SIM | Informar o CEP do Responsável | |
| enderecoResp | VARCHAR(60) | NÃO | Informar somente o endereço | |
| numeroEndResp | VARCHAR(10) | SIM | Informar o número do endereço | |
| bairroResp | VARCHAR(60) | NÃO | Informar o Bairro do Endereço | |
| cidadeResp | VARCHAR(60) | NÃO | Nome da Cidade do Responsável | |
| siglaEstadoResp | VARCHAR(02) | NÃO | Sigla do Estado do Responsável | |
| emailResp | VARCHAR(60) | SIM | Email do Responsável | |
| foneRes | VARCHAR(20)(XX)XXXX-XXXX | SIM | Telefone Residencial | |
| foneCel | VARCHAR(20)(XX)XXXXX-XXXX | SIM | Telefone Celular | |
| foneCom | VARCHAR(20)(XX)XXXX-XXXX | SIM | Telefone Comercial | |
| parcelaDest | Lista | NÃO | Nesta Tag serão passadas várias informações das parcelas de geradas da renegociação, que pertencem ao responsável informado. Deve-se informar os atributos de parâmetros gerais, e caso deseje gerar título, deverá informar também os atributos de dados para geração de título. | |
| Parâmetros gerais: | ||||
| datVctPar | DATE | NÃO | Data de Vencimento da Parcela | |
| valBru | NUMERIC(18,2) | NÃO | Valor Bruto da Nova parcela | |
| cfPar | INT | NÃO | ID da conta financeira na qual a parcela será renegociada | |
| nroPar | INT | NÃO | Número da parcela a ser gerada | |
| valJurFut | NUMERIC(18,2) | NÃO | Valor dos juros futuros que serão cobrados. Enviar 0,00 se não for cobrar. | |
| indexFut | NUMERIC(18,2) | NÃO | Valor do indexador futuro que será cobrado. Enviar 0,00 se não for cobrar. | |
| mesAnoComp | VARCHAR(7) | NÃO | MM/AAAA (MÊS/ANO) de competência da parcela. | |
| idPlano | INT | NÃO | ID do plano de pagamento do MentorWeb responsável pela renegociação. | |
| titulo | VARCHAR | NÃO | Valores possíveis: → TERCEIRO: quando o sistema terceiro já manda as informações do título gerado; → MENTOR: quando a responsabilidade de geração de título é do Mentor; → SEM_TITULO: não gera título bancário. Neste caso, não pode ser informado nenhum dos parâmetros relacionados à título bancário; | |
| infoReciboPagador | VARCHAR(8000) | Sim | Informações que constarão no recibo do pagador | |
| codParcelaExterna | INT | Sim | Campo que armazena o código da parcela externa, quando possuir, caso informado, ao gerar a renegociação enviará o valor informado para a parcela destino. | |
| Dados para geração de título (somente informá-los quando deseja gerar título): | ||||
| contaBancaria | INT | Sim (condicional) | Informar o ID da conta bancária utilizada na geração. Deve existir no Mentor Web. Informar somente quando deseja-se gerar título para a parcela de destino e a conta financeira da parcela indicar geração de título. | |
| nossoNumero | INT | Sim (condicional) | Nosso número da parcela sem digito verificador Informar somente quando deseja-se gerar título para a parcela de destino e a conta financeira da parcela indicar geração de título. | |
| digitoNumero | VARCHAR(02) | Sim (condicional) | Dígito do nosso número. Informar somente quando deseja-se gerar título para a parcela de destino e a conta financeira da parcela indicar geração de título. | |
| linDig | VARCHAR(255) | Sim (condicional) | Linha digitável do título. Exemplo: 00190.00009 00310.606280 00000.000182 8 13420000016200 Informar somente quando deseja-se gerar título para a parcela de destino e a conta financeira da parcela indicar geração de título. | |
| instru | VARCHAR(8000) | Sim (condicional) | Instrução de cobrança a ser impressa no boleto. Se não houver enviar pelo menos um espaço em branco. Informar somente quando deseja-se gerar título para a parcela de destino e a conta financeira da parcela indicar geração de título. | |
| sacado | VARCHAR(8000) | Sim (condicional) | Informar os dados dos sacado. Informar somente quando deseja-se gerar título para a parcela de destino e a conta financeira da parcela indicar geração de título. | |
| nroDoc | VARCHAR(400) | Sim (condicional) | Número do documento. Informar somente quando deseja-se gerar título para a parcela de destino e a conta financeira da parcela indicar geração de título. | |
| moeda | VARCHAR(20) | Sim (condicional) | Informar a moeda do título Informar somente quando deseja-se gerar título para a parcela de destino e a conta financeira da parcela indicar geração de título. | |
| datVctTit | DATE (dd/mm/aaaa) | Sim (condicional) | Informar a data de vencimento do título. Informar somente quando deseja-se gerar título para a parcela de destino e a conta financeira da parcela indicar geração de título. | |
| seuNumero | INT | Sim (condicional) | Informar o seu número. Caso não utilize, repetir o nosso número. Informar somente quando deseja-se gerar título para a parcela de destino e a conta financeira da parcela indicar geração de título. | |
| carteira | VARCHAR(40) | Sim (condicional) | Código da carteira de cobrança. Informar somente quando deseja-se gerar título para a parcela de destino e a conta financeira da parcela indicar geração de título. | |
| datValTit | DATE(dd/mm/aaaa) | Sim (condicional) | Data de validade do boleto. Informar somente quando deseja-se gerar título para a parcela de destino e a conta financeira da parcela indicar geração de título. | |
| - | ||||
| descontos | Lista | Sim | Nesta Tag serão passadas as informações para geração do desconto nas parcelas de destino. | |
| descontoId | INT | Não | A instituição deverá fornecer o identificador do desconto para o sistema terceiro | |
| descontoValor | NUMERIC(18,2) | Não | Valor do desconto que será concedido | |
| descontoDataValidade | DATE (dd/mm/aaaa) | Sim | Data de validade do desconto. Quando for um desconto sem limite de validade, não é necessário informar. | |
Os atributos riscados estão depreciados, ou seja, não irá fazer diferença para nós se for informado valor ou não, pois eles não serão utilizados.
Para valores numéricos, na qual não é obrigatório, caso não queira informar valor, deverá ser enviado valor null conforme exemplo abaixo:
"nossoNumero": null
Para valores Varchar, na qual não é obrigatório, caso não queira informar valor, deverá ser enviado valor vazio (“”) conforme exemplo abaixo:
"sacado": ""
Parcelas de destino - geração de título:
Informar apenas quando permite geração de título:
Os parâmetros condicionais relacionados a geração de título só deverão ser informados quando dentro do Mentor em Financeiro > Contas financeiras > Configurações > Gerar título, o parâmetro de geração estiver marcado e deseja-se gerar título para a parcela de destino. Porém, se o parâmetro estiver desmarcado não deve-se informar os campos, assim como não se pode informar somente alguns dos campos obrigatórios quando é optado por gerar o título. Por fim, se o parâmetro estiver marcado, mas deseja-se não gerar, é só não informar os campos que a geração não irá ocorrer.
2. Exemplo de chamada do Serviço
URL: http://IP:PORTA/APLICACAO/rest/servicoexterno/execute/realizaRenegociacao
2.1. Exemplo da passagem de parâmetros por Json:
{ "dataRen": "14/02/2019 10:26:42", "observ": "feito pelo serviço", "usuario": "admin", "honorario": 10.31, "custaJudic": 15.31, "clausulaPen": 20.31, "descon": 0.02, "acresc": 0.62, "permiteRenegociadas": 0, "datbaixaParRen": "DATAATU", "tipoBai": 1, "parcelaOri": [ { "parId": 5364590, "periodoLet": "30/11/2018 10:26:42" } ], "resp": { "cpfResp": "17023596895", "nomeResp": "Adriana Paula Pereira Cardoso ", "cepResp": "89040400", "enderecoResp": "Rua São Paulo", "numeroEndResp": "50", "bairroResp": "Centro", "cidadeResp": "Blumenau", "siglaEstadoResp": "SC", "emailResp": "[email protected]", "foneRes": "(47)9999-9999", "foneCel": "(47)99999-9999", "foneCom": "(47)9999-9999" }, "parcelaDest": [ { "datVctPar": "02/09/2019 10:26:42", "valBru": 209.01, "cfPar": 1, "nroPar": 1, "valJurFut": 13.06, "indexFut": 0.0, "mesAnoComp": "09/2019", "idPlano": 169, "titulo": "MENTOR", "nossoNumero": "9640691", "digitoNumero": "1", "linDig": "03399.12735 36110.000027 73753.701017 5 78150000048916", "instru": "instrucao do boleto", "sacado": "Nome do sacado", "carteira": "SANTANDER_COB", "nroDoc": "564566", "moeda": "01", "datVctTit": "20/02/2018 10:26:42", "contaBancaria": 15, "datValTit": "20/02/2018 10:26:42", "seuNumero": "12345678987", "descontos": [ { "descontoId": 343, "descontoValor": 2.41, "descontoDataValidade": "11/06/2020" }, { "descontoId": 343, "descontoValor": 8.42, "descontoDataValidade": "" }, { "descontoId": 312, "descontoValor": 10.41, "descontoDataValidade": "" } ] }, { "datVctPar": "02/09/2019 10:26:42", "valBru": 192.01, "cfPar": 1, "nroPar": 2, "valJurFut": 13.06, "indexFut": 0.0, "mesAnoComp": "09/2019", "idPlano": 169, "titulo": "MENTOR", "nossoNumero": "9640690", "digitoNumero": "1", "linDig": "03399.12735 36110.000027 73753.701017 5 78150000048917", "instru": "instrucao do boleto", "sacado": "Nome do sacado", "carteira": "SANTANDER_COB", "nroDoc": "564566", "moeda": "01", "datVctTit": "20/03/2018 10:26:42", "contaBancaria": 15, "datValTit": "20/03/2018 10:26:42", "seuNumero": "12345678987", "infoReciboPagador":"Boleto referente ao pagamento da parcela da disciplina xyz" } ] }
2.2. Exemplo de chamada do serviço no PostMan
Para baixar o arquivo PostMan com o exemplo da chamada do serviço externo, clique aqui. Lembre-se de modificar os parâmetros e o endereço da chamada.
3. Retorno do serviço (Json)
Para obter o retorno do serviço deve-se verificar o status da requisição http.
Sempre que o status for 200, significa que o processo foi realizado com sucesso.
3.1. Atributos retornados do serviço para o chamador
| Campo | Descrição | Tipo | Observação |
|---|---|---|---|
| logProcessoId | Identificador do log de processo | Integer | Pode ser utilizado no MentorWeb na tela de consulta de log, para consultar o log gerado. |
| quantidadeLancamentos | Quantidade de lançamentos que foram gerados | Integer | - |
| resultado | Retorna a situação do resultado | String(7) | Valores possíveis: SUCESSO / ERRO |
3.2. Exemplo de retorno Json com sucesso:
Quando ocorre sucesso, o status de retorno http é o código 200 (Ok).
{ "valor": "Renegociação realizada com sucesso.", "resultado": "SUCESSO" }
3.3. Exemplo de retorno Json com erro:
Quando ocorre sucesso, o status de retorno http é é diferente do código 200 (Ok), ou seja, qualquer outro código considerar como inconsistência.
{ "resultado":"ERRO", "erro":{ "operacao":"br.com.edusoft.mentorweb.servico.controller.ServicoExternoFinanceiroImplJava.realizaRenegociacao", "valores":{ "dataRen":"14/02/2019 10:26:42", "observ":"feito pelo serviço", "usuario":"admin", "honorario":10.31, "custaJudic":15.31, "clausulaPen":20.31, "descon":0.02, "acresc":0.62, "permiteRenegociadas":0, "datbaixaParRen":"DATAATU", "tipoBai":1, "parcelaOri":[ { "parId":5364590, "periodoLet":"30/11/2018 10:26:42" } ], "resp":{ "cpfResp":"17023596895", "nomeResp":"Adriana Paula Pereira Cardoso ", "cepResp": "89040400", "enderecoResp":"Rua São Paulo", "numeroEndResp":"50", "bairroResp":"Centro", "cidadeResp":"Blumenau", "siglaEstadoResp":"SC", "emailResp":"[email protected]", "foneRes":"(47)9999-9999", "foneCel":"(47)99999-9999", "foneCom":"(47)9999-9999" }, "parcelaDest":[ { "datVctPar":"02/09/2019 10:26:42", "valBru":209.01, "cfPar":1, "nroPar":1, "valJurFut":13.06, "indexFut":0.0, "mesAnoComp":"09/2019", "idPlano":169, "titulo":"MENTOR", "nossoNumero":"9640691", "digitoNumero":"1", "linDig":"03399.12735 36110.000027 73753.701017 5 78150000048916", "instru":"instrucao do boleto", "sacado":"Nome do sacado", "carteira":"SANTANDER_COB", "nroDoc":"564566", "moeda":"01", "datVctTit":"20/02/2018 10:26:42", "contaBancaria":15, "datValTit":"20/02/2018 10:26:42", "seuNumero":"12345678987" }, { "datVctPar":"02/09/2019 10:26:42", "valBru":192.01, "cfPar":1, "nroPar":2, "valJurFut":13.06, "indexFut":0.0, "mesAnoComp":"09/2019", "idPlano":169, "titulo":"MENTOR", "nossoNumero":"9640690", "digitoNumero":"1", "linDig":"03399.12735 36110.000027 73753.701017 5 78150000048917", "instru":"instrucao do boleto", "sacado":"Nome do sacado", "carteira":"SANTANDER_COB", "nroDoc":"564566", "moeda":"01", "datVctTit":"20/03/2018 10:26:42", "contaBancaria":15, "datValTit":"20/03/2018 10:26:42", "seuNumero":"12345678987", "infoReciboPagador":"Boleto referente ao pagamento da parcela da disciplina xyz" } ] }, "motivo":"EduClientLogProcessoException: O código da conta financeira da parcela de origem não é o mesmo que consta no MentorWeb." } }
Informações importantes:
1. Para criar/atualizar a pessoa, é verificado o CPF. Se existe atualiza, se não existe, cria;
2. A cada renegociação é criado um novo contrato, utilizando no nome “Renegociação”, e vai incrementando uma numeração ao final caso já exista com a descrição atual. Tenta-se até no máximo 20 tentativas, caso mesmo assim encontre contrato com mesmo nome, é gerado exceção;
3. As parcelas de destino tem que ter a mesma conta bancária, mesma conta financeira e mesmo plano de pagamento. Caso sejam diferentes, irá gerar exceção e gravar log.
4. O contrato financeiro da renegociação não possuirá curso e turma informado. Além disso, o período letivo do contrato será definido com base no parâmetro periodoLet, porém, somente será informado o período letivo no contrato de renegociação caso o contrato de origem possua período letivo, caso contrário, ficará vazio.
5.Os descontos informados nas parcelas de destino somente serão considerados quando quem gera o título é o sistema terceiro. Quando o título é gerado pelo MentorWeb os descontos deverão estar no contrato financeiro, normalmente.
6. O plano de pagamento não pode ter parcelas, nem mesmo parcela de inscrição. Caso contrário, irá poderá gerar erros no processo da renegociação.
7. Somente será gerado o título da renegociação caso a conta financeira da primeira parcela esteja com a configuração “Gera título” marcado. Se na conta financeira da primeira parcela de destino estiver com a opção marcado, irá gerar título para todas as parcelas de destino. Caso contrário, não irá gerar título para nenhuma das parcelas de destino.