Simulação de parcelamentos de uma fatura
stable
Este endpoint permite que o cliente do parceiro Bankly simule os possíveis parcelamentos de uma fatura.
Pré-requisitos
Para que seja possível utilizar este endpoint, é necessário que:
- A fatura do cliente esteja fechada;
- A fatura seja elegível a parcelamento.
Requisição (Request)
Requisição HTTP
POST https://api-mtls.sandbox.bankly.com.br/cards/invoices/{statementId}/installments \
--request POST \
--url 'https://api-mtls.sandbox.bankly.com.br/cards/invoices/{statementId}/installments' \
--header 'Authorization: Bearer {Token}' \
--header 'accept: appication/json' \
--header 'api-version: 1'
--data '{
"minTerm": 2,
"maxTerm": 5,
"downPayment": 20.0
} '
Autorização
Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.
Esta requisição requer o scope descrito a seguir:
Scope | Descrição |
---|---|
invoice.read | Concede acesso para realizar consultas referentes à gestão de faturas. |
Cabeçalhos (Headers)
Nome | Descrição |
---|---|
api-version | Obrigatório. Versão da API. Atualmente estamos na versão 1.0. |
Authorization | Obrigatório. Token de autorização do tipo Bearer. |
Parâmetros da rota (Path)
No path desta requisição, envie o seguinte campo:
Nome | Tipo | Descrição |
---|---|---|
statementId | path | Obrigatório. Identificador único da fatura, retornado na consulta de todas as faturas. |
Corpo da requisição (Body)
No body, envie os seguintes campos em formato JSON:
Nome | Tipo | Descrição | Especificação |
---|---|---|---|
minTerm | integer | Obrigatório. Número mínimo de parcelas a serem antecipadas. | Mínimo de duas parcelas. |
maxTerm | integer | Obrigatório. Número máximo de parcelas a serem antecipadas. | Mínimo de duas parcelas. |
downPayment | number | Valor de entrada para simulação. | decimal (18,4) |
Importante
Se o número máximo de parcelas (
maxTerm
) informado exceder o permitido pela configuração do programa vinculado à fatura, será retornado apenas o número máximo de parcelas permitido.
{
"minTerm": 2,
"maxTerm": 4,
"downPayment": 20.0
}
Resposta (Response)
O status code 200 indicará que a solicitação foi aceita e retornará uma lista com os possíveis parcelamentos e suas informações.
Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:
Nome | Tipo | Descrição | Número máximo de caracteres |
---|---|---|---|
paymentOptionId | integer | Identificador único da opção de pagamento. | 10 |
statementId | integer | Identificador único da fatura. | 10 |
paymentType | string | Opção de pagamento, que pode ser: “Cash” (à vista), “Partial” (parcial), “InstallmentWithEntry” (parcelado com entrada) e “InstallmentWithoutEntry” (parcelado sem entrada). | 40 |
value | number | Valor a ser pago (no caso de parcelamento, será a entrada). | decimal (18,4) |
creditOffer | object | Objeto que contém informações sobre a proposta de parcelamento da fatura. | — |
creditOffer.creditOfferId | integer | Identificador único da proposta. | 10 |
creditOffer.externalOperationId | string | Identificador externo da operação. | 40 |
creditOffer.externalOfferId | string | Identificador externo da proposta. | 40 |
creditOffer.externalOfferType | string | Tipo da proposta externa retornada, que pode ser “Variable” (referente à proposta de parcelamento) ou “Fixed” (referente à proposta de crédito rotativo). | 50 |
creditOffer.amountCurrency | string | Código da moeda com base na ISO-4217 (exemplo: BRL). | 4 |
creditOffer.amountDue | number | Valor contratado da proposta mais o valor total de juros (pode ou não conter TAC). | decimal (18,4) |
creditOffer.annualCet | number | CET (custo efetivo total) da contratação calculado ao ano. | decimal (18,4) |
creditOffer.annualInterestRate | number | Taxa de juros anual da contratação. | decimal (18,4) |
creditOffer.cet | number | CET (custo efetivo total) da contratação calculado na periodicidade definida das parcelas. | decimal (18,4) |
creditOffer.disbursementDate | string | Data prevista para o desembolso da proposta. | 29 |
creditOffer.externalCreatedAt | string | Data do cálculo da proposta, no formato ISO 8601. | 29 |
creditOffer.externalExpiresAt | string | Data de expiração da proposta, no formato ISO 8601. | 29 |
creditOffer.firstPaymentDate | string | Data do primeiro pagamento da proposta, no formato ISO 8601. | 29 |
creditOffer.graceDays | integer | Quantidade de dias para a carência do primeiro pagamento. | 30 |
creditOffer.lastPaymentDate | string | Data do último pagamento da proposta, no formato ISO 8601. | 292 |
creditOffer.loanAmount | number | Valor do crédito solicitado para contratação. | decimal (18,4) |
creditOffer.monthlyInterestRate | number | Taxa de juros mensal da contratação. | decimal (18,4) |
creditOffer.operationCostAmount | number | Custo de processamento da operação. | decimal (18,4) |
creditOffer.retentionRate | number | Indica o percentual de retenção da proposta. | decimal (18,4) |
creditOffer.term | integer | Quantidade de parcelas da proposta. | 2 |
creditOffer.totalInterestAmount | number | Valor total de juros a ser pago na contratação. | decimal (18,4) |
creditOffer.totalPaymentAmount | number | Valor total a ser pago no final do contrato (se aplicável ao produto). | decimal (18,4) |
creditOffer.iofTotalAmount | number | Valor final do cálculo do IOF. | decimal (18,4) |
creditOffer.iofTotalPercentage | number | Valor percentual do IOF, se aplicável. | decimal (18,4) |
creditOffer.confirmedOffer | boolean | Informa se a oferta está confirmada. | — |
creditOffer.diaryIof | number | Informa o percentual do IOF diário. | decimal (18,4) |
creditOffer.fixedIof | number | Informa o percentual do IOF fixo. | decimal (18,4) |
creditOffer.Installments[] | array of objects | Lista de objetos contendo os parcelamentos e suas informações. | — |
creditOffer.Installments[].creditOfferId | integer | Identificador único da proposta. | 20 |
creditOffer.Installments[].amortizationAmount | number | Valor da amortização no contrato. | decimal (18,4) |
creditOffer.Installments[].dueDate | string | Data de vencimento da parcela, no formato ISO 8601. | 29 |
creditOffer.Installments[].interestAmount | number | Valor dos juros da parcela. | decimal (18,4) |
creditOffer.Installments[].iofAmount | number | Valor do IOF da parcela. | decimal (18,4) |
creditOffer.Installments[].paymentAmount | number | Valor da parcela. | decimal (18,4) |
creditOffer.Installments[].installmentNumber | integer | Número da parcela. | 2 |
[
{
"paymentOptionId": 0,
"statementId": 0,
"paymentType": "Cash",
"value": 0.0,
"creditOffer": {
"creditOfferId": 0,
"externalOperationId": "string",
"externalOfferId": "string",
"externalOfferType": "string",
"amountCurrency": "string",
"amountDue": 0.0,
"annualCet": 0.0,
"annualInterestRate": 0.0,
"cet": 0.0,
"disbursementDate": "2025-04-28T00:00:00+00:00",
"externalCreatedAt": "2025-04-28T00:00:00+00:00",
"externalExpiresAt": "2025-04-28T00:00:00+00:00",
"firstPaymentDate": "2025-04-28T00:00:00+00:00",
"graceDays": 0,
"lastPaymentDate": "2025-04-28T00:00:00+00:00",
"loanAmount": 0.0,
"monthlyInterestRate": 0,
"operationCostAmount": 0,
"retentionRate": 0,
"term": 0,
"totalInterestAmount": 0,
"totalPaymentAmount": 0,
"iofTotalAmount": 0,
"iofTotalPercentage": 0,
"confirmedOffer": true,
"diaryIof": 0.5,
"fixedIof": 1.5,
"installments": [
{
"creditOfferId": 0,
"amortizationAmount": 0,
"dueDate": "2025-04-28T00:00:00+00:00",
"interestAmount": 0,
"iofAmount": 0,
"paymentAmount": 0,
"installmentNumber": 0
}
]
}
}
]
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.
Erros
Este endpoint pode retornar alguns erros específicos, conforme a tabela a seguir:
Status Code | Código | Mensagem | Descrição |
---|---|---|---|
400 | CONTRACT_IS_IN_CRELIQ | Contract from statment is Creliq status. | Contrato da declaração está em status Creliq. |
406 | STATEMENT_IS_NOT_CLOSED | Statement is not closed! | A fatura não está fechada. |
406 | CANT_MAKE_A_NEW_SIMULATION | Can't make a new simulation, a payment for the invoice has already been made | Não é possível realizar uma nova simulação, pois já existe um pagamento atrelado à fatura. |
406 | INVALID_ENTRY_TYPE_FOR_PROGRAM | The program associated with the invoice does not allow custom entry | O programa associado à fatura não permite entrada personalizada. |
406 | ENTRY_TYPE_NOT_CONFIGUED_FOR_PROGRAM | The program associated with the invoice have not configured custom entry settings | O programa vinculado à fatura não foi configurado para permitir entrada personalizada. |
406 | DOWN_PAYMENT_MINIMAL_NOT_ALLOWED | The down payment amount cannot be less than the allowed minimum | O valor de entrada não pode ser menor que o permitido. |
406 | INVALID_DOWN_PAYMENT_AMOUNT | The down payment amount cannot be equal to another active credit offer's down payment | O valor de entrada não pode ser idêntico ao valor de entrada de outra oferta de crédito ativa. |
406 | DOWN_PAYMENT_CANNOT_BE_EQUAL_AMOUNT_MINIMUM | The down payment amount cannot be equal of amount minimum | O valor da entrada não pode ser igual ao valor mínimo da fatura. |
406 | EXISTING_CREDIT_OFFER_WITH_PAYMENT | Can't make a new simulation, a payment for an active credit offer has already been made | Não é possível realizar uma nova simulação, pois já existe um pagamento atrelado à alguma oferta de crédito ativa. |
406 | SIMULATION_ALREADY_MADE | A simulation already exists with the provided custom entry | Já existe uma simulação com a entrada personalizada fornecida. |
Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400 (se houver).
Eventos
Este endpoint não possui eventos relacionados a ele.
Updated about 1 month ago