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.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| agreementRuleId | integer | Obrigatório | Regra que define o custo e os limites do acordo. Precisa estar ativa e vinculada à conta ou ao programa da fatura. |
| invoiceId | integer | Obrigatório | Fatura a ser parcelada. |
| installmentQuantity | integer | Obrigatório | Quantidade de parcelas. Precisa estar entre minimumInstallments e maximumInstallments da regra. |
| downPayment | decimal | Opcional | Valor de entrada informado manualmente. Quando enviado, precisa respeitar manualMinEntry e manualMaxEntry da regra. |
Request:
{
"agreementRuleId": 1,
"invoiceId": 1,
"installmentQuantity": 3,
"downPayment": 100
}POST/installments/simulateCalcula o plano completo sem contratá-lo. Use o retorno para montar a tela de confirmação do portador.
{
"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"
}
]
}
}
POST/installments/Cria o acordo e o cronograma de parcelas. O corpo da resposta tem a mesma estrutura da simulação.
GET/installments/| Filtro | Tipo | Descrição |
|---|---|---|
| paymentAgreementId | integer | Um acordo específico. |
| agreementRuleId | integer | Todos os acordos gerados por uma regra. |
| invoiceId | integer | Acordos de uma fatura. Use este filtro antes de recriar um acordo. |
| accountId | integer | Acordos de uma conta. |
| origin | string | Origem da criação do parcelamento. |
| status | string | Descrição do status, não o id. Ex.: ACORDO SIMULADO. |
| installments | boolean | Quando true, inclui o array agreementInstallments no retorno. |
| invoicePlan | boolean | Quando true, retorna apenas os acordos que compõem a fatura. |
| page | integer | Página da listagem. |
| perPage | integer | Quantidade de acordos por página. |
DELETE
/installments/cancel/{installment}O path recebe o paymentAgreementId do acordo.
{
"message": "Your cancellation request is being processed"
}
Campos do acordo
| Campo | Tipo | Descrição |
|---|---|---|
| paymentAgreementId | integer | Identificador do acordo. |
| agreementRuleId | integer | Regra que originou o acordo. |
| invoiceId | integer | Fatura parcelada. |
| agreementStatus | string | Status atual. Ver GET /installments/status. |
| origin | string | Origem da criação do parcelamento. |
| adhesionDate | date-time | Data de adesão ao acordo. |
| presentValue | decimal | Valor presente da operação. |
| agreementAmount | decimal | Valor total do acordo. |
| contractBalance | decimal | Saldo devedor do contrato. |
| entryValue | decimal | Valor da entrada. |
| installmentCount | integer | Quantidade de parcelas do acordo. |
| interestAmount | decimal | Total de juros do acordo. |
| dailyIofAmount | decimal | Valor do IOF diário. |
| additionalIofAmount | decimal | Valor do IOF adicional. |
| monthlyCET | decimal | Custo Efetivo Total mensal. |
| annualCET | decimal | Custo Efetivo Total anual. |
| creationDate | date-time | Criação do registro. |
| updateDate | date-time | Última atualização do registro. |
| agreementInstallments | array | Cronograma de parcelas. Retornado quando installments=true. |
Campos da parcela
| Campo | Tipo | Descrição |
|---|---|---|
| agreementInstallmentId | integer | Identificador da parcela. |
| paymentAgreementId | integer | Acordo ao qual a parcela pertence. |
| installmentNumber | integer | Número da parcela na sequência. |
| invoiceId | integer | Fatura em que a parcela é lançada. |
| installmentStatus | string | Status da parcela. Ex.: ABERTA. |
| totalAmount | decimal | Valor total da parcela. |
| principalAmount | decimal | Parcela do principal. |
| interestAmount | decimal | Juros da parcela. |
| interestRatePercentage | decimal | Taxa de juros aplicada à parcela. |
| iofAmount | decimal | IOF da parcela. |
| dailyIofAmount | decimal | IOF diário da parcela. |
| description | string | Descrição da parcela. |
| creationDate | date-time | Criação do registro. |
| updateDate | date-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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| accountId | integer | Obrigatório | Conta cujas simulações serão listadas. |
| startDate | date | Obrigatório | Data inicial do período. |
| endDate | date | Obrigatório | Data final do período. |
| statementId | integer | Opcional | Restringe o histórico a um statement. |
| No histórico | No resto da API | Observação |
|---|---|---|
| statusAcordoId | agreementStatus | Aqui é o id numérico; lá é a descrição. |
| installmentsNumber | installmentCount | — |
| entryAmount | entryValue | — |
| dailyIOFAmount | dailyIofAmount | Diferença de caixa em IOF. |
| aditionalIOFAmount | additionalIofAmount | Grafia com um d apenas. |
| acordosParcelas | agreementInstallments | Nome em português. |
| installmentAmount | totalAmount | Dentro do array de parcelas. |
| dailyIOF / aditionalIOF | dailyIofAmount / iofAmount | Dentro do array de parcelas. |
| status | installmentStatus | Aqui é 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
{
"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!"
}
Updated about 5 hours ago