Simulação e contratação de acordo

Com a regra configurada e vinculada, o parcelamento de uma fatura acontece em duas chamadas: uma que calcula o plano e mostra o custo ao portador, e outra que transforma esse plano em contrato.

Fluxo

Corpo da requisição

A simulação e a contratação usam exatamente os mesmos quatro campos.

CampoTipoObrigatórioDescrição
agreementRuleIdintegerObrigatórioRegra que define o custo e os limites do acordo. Precisa estar ativa e vinculada à conta ou ao programa da fatura.
invoiceIdintegerObrigatórioFatura a ser parcelada.
installmentQuantityintegerObrigatórioQuantidade de parcelas. Precisa estar entre minimumInstallments e maximumInstallments da regra.
downPaymentdecimalOpcionalValor de entrada informado manualmente. Quando enviado, precisa respeitar manualMinEntry e manualMaxEntry da regra.

Request:

{
  "agreementRuleId": 1,
  "invoiceId": 1,
  "installmentQuantity": 3,
  "downPayment": 100
}
  1. Simular

POST/installments/simulate

Calcula o plano completo sem contratá-lo. Use o retorno para montar a tela de confirmação do portador.

👍

Sucesso 200

{
  "version": "1.0.0",
  "status": 200,
  "body": {
    "paymentAgreementId": 1,
    "agreementRuleId": 1,
    "invoiceId": 1,
    "agreementStatus": "ACORDO SIMULADO",
    "origin": "MANUAL",
    "adhesionDate": "2024-07-05T21:05:47.000000Z",
    "presentValue": 1000,
    "agreementAmount": 200,
    "contractBalance": 200,
    "entryValue": 220,
    "installmentCount": 5,
    "interestAmount": 380.25,
    "dailyIofAmount": 8.76,
    "additionalIofAmount": 4,
    "monthlyCET": 2.5,
    "annualCET": 34.49,
    "creationDate": "2024-07-05T21:05:47.000000Z",
    "updateDate": "2024-07-05T21:05:47.000000Z",
    "agreementInstallments": [
      {
        "agreementInstallmentId": 1,
        "paymentAgreementId": 1,
        "installmentNumber": 1,
        "invoiceId": 1,
        "installmentStatus": "ABERTA",
        "totalAmount": 115,
        "principalAmount": 100,
        "interestAmount": 10,
        "interestRatePercentage": 0.1,
        "iofAmount": 5,
        "dailyIofAmount": 5,
        "description": "Exemplo",
        "creationDate": "2024-07-05T21:05:47.000000Z",
        "updateDate": "2024-07-05T21:05:47.000000Z"
      }
    ]
  }
}
  1. Contratar

POST/installments/

Cria o acordo e o cronograma de parcelas. O corpo da resposta tem a mesma estrutura da simulação.

  1. Consultar acordos

GET/installments/
FiltroTipoDescrição
paymentAgreementIdintegerUm acordo específico.
agreementRuleIdintegerTodos os acordos gerados por uma regra.
invoiceIdintegerAcordos de uma fatura. Use este filtro antes de recriar um acordo.
accountIdintegerAcordos de uma conta.
originstringOrigem da criação do parcelamento.
statusstringDescrição do status, não o id. Ex.: ACORDO SIMULADO.
installmentsbooleanQuando true, inclui o array agreementInstallments no retorno.
invoicePlanbooleanQuando true, retorna apenas os acordos que compõem a fatura.
pageintegerPágina da listagem.
perPageintegerQuantidade de acordos por página.
  1. Cancelar

DELETE
/installments/cancel/{installment}

O path recebe o paymentAgreementId do acordo.

👍

Sucesso 200


{
  "message": "Your cancellation request is being processed"
}

Campos do acordo

CampoTipoDescrição
paymentAgreementIdintegerIdentificador do acordo.
agreementRuleIdintegerRegra que originou o acordo.
invoiceIdintegerFatura parcelada.
agreementStatusstringStatus atual. Ver GET /installments/status.
originstringOrigem da criação do parcelamento.
adhesionDatedate-timeData de adesão ao acordo.
presentValuedecimalValor presente da operação.
agreementAmountdecimalValor total do acordo.
contractBalancedecimalSaldo devedor do contrato.
entryValuedecimalValor da entrada.
installmentCountintegerQuantidade de parcelas do acordo.
interestAmountdecimalTotal de juros do acordo.
dailyIofAmountdecimalValor do IOF diário.
additionalIofAmountdecimalValor do IOF adicional.
monthlyCETdecimalCusto Efetivo Total mensal.
annualCETdecimalCusto Efetivo Total anual.
creationDatedate-timeCriação do registro.
updateDatedate-timeÚltima atualização do registro.
agreementInstallmentsarrayCronograma de parcelas. Retornado quando installments=true.

Campos da parcela

CampoTipoDescrição
agreementInstallmentIdintegerIdentificador da parcela.
paymentAgreementIdintegerAcordo ao qual a parcela pertence.
installmentNumberintegerNúmero da parcela na sequência.
invoiceIdintegerFatura em que a parcela é lançada.
installmentStatusstringStatus da parcela. Ex.: ABERTA.
totalAmountdecimalValor total da parcela.
principalAmountdecimalParcela do principal.
interestAmountdecimalJuros da parcela.
interestRatePercentagedecimalTaxa de juros aplicada à parcela.
iofAmountdecimalIOF da parcela.
dailyIofAmountdecimalIOF diário da parcela.
descriptionstringDescrição da parcela.
creationDatedate-timeCriação do registro.
updateDatedate-timeÚltima atualização do registro.

Status do acordo

Consulte a lista vigente em GET /installments/status, que devolve agreementStatusId e description.

ACORDO SIMULADO - agreementStatusId: 1. Plano calculado, ainda sem contrato efetivado.

Histórico de simulações

GET/installments/simulation/history

Recupera as simulações de uma conta em um período. Útil para auditoria e para atendimento ao portador.

ParâmetroTipoObrigatórioDescrição
accountIdintegerObrigatórioConta cujas simulações serão listadas.
startDatedateObrigatórioData inicial do período.
endDatedateObrigatórioData final do período.
statementIdintegerOpcionalRestringe o histórico a um statement.
No históricoNo resto da APIObservação
statusAcordoIdagreementStatusAqui é o id numérico; lá é a descrição.
installmentsNumberinstallmentCount—
entryAmountentryValue—
dailyIOFAmountdailyIofAmountDiferença de caixa em IOF.
aditionalIOFAmountadditionalIofAmountGrafia com um d apenas.
acordosParcelasagreementInstallmentsNome em português.
installmentAmounttotalAmountDentro do array de parcelas.
dailyIOF / aditionalIOFdailyIofAmount / iofAmountDentro do array de parcelas.
statusinstallmentStatusAqui é numérico; lá é texto.

Os valores monetários vêm como string neste endpoint ("1000.00"), e não como número. Converta antes de fazer contas.

Response

👍

Sucesso 200

{
  "version": "1.0.1",
  "status": 200,
  "body": [
    {
      "agreementRuleId": 123,
      "invoiceId": 456,
      "statusAcordoId": 1,
      "presentValue": "1000.00",
      "agreementAmount": "1200.00",
      "entryAmount": "100.00",
      "installmentsNumber": 12,
      "interestAmount": "200.00",
      "dailyIOFAmount": "2.50",
      "aditionalIOFAmount": "5.00",
      "monthlyCET": 2.5,
      "annualCET": 30,
      "origin": "MANUAL",
      "acordosParcelas": [
        {
          "installmentNumber": 1,
          "installmentAmount": "100.00",
          "status": 1,
          "principalAmount": "90.00",
          "interestAmount": "8.50",
          "interestRatePercentage": 2.5,
          "dailyIOF": "0.50",
          "aditionalIOF": "1.00",
          "description": "1",
          "invoiceId": 456
        }
      ]
    }
  ]
}

Adesão no core de cartões:

POST/installments/publish

Efetiva a adesão ao acordo de pagamento no core de cartões.

Request:

{
  "invoiceId": 1,
  "amountInstallment": 3,
  "statementAgreement": "false"
}

Response

{
  "version": "1.0.0",
  "status": 200,
  "body": "Adesão ao acordo de pagamento realizada com sucesso!"
}

Did this page help you?