Simulador de Venda

Este endpoint permite realizar a simulação de uma venda, calculando os valores de pagamento para diferentes métodos (Pix, Boleto e Cartão de Crédito) com base no valor total e no número de parcelas desejado.

Simular Pagamento

[POST] /billing/simulate-payment

Calcula o valor das parcelas e o total acumulado para cada método de pagamento.

Headers

Nome	Tipo	Obrigatório	Descrição
Authorization	Bearer Token	Sim	Token de acesso do usuário.
Content-Type	string	Sim	application/json
account	integer	Sim	ID da conta ativa.

Body (JSON)

Nome	Tipo	Obrigatório	Descrição	Exemplo
amount	numeric	Sim	Valor total da cobrança.	1200.00
installments	integer	Sim	Número de parcelas (1 a 12).	10

---

Resposta de Sucesso (200 OK)

{
  "success": true,
  "message": "Simulação realizada com sucesso.",
  "data": {
    "pix": {
      "method": "pix",
      "installments": 1,
      "installment_value": 1200.0,
      "total_amount": 1200.0
    },
    "boleto": {
      "method": "boleto",
      "installments": 1,
      "installment_value": 1200.0,
      "total_amount": 1200.0
    },
    "credit_card": {
      "method": "credit_card",
      "installments": 10,
      "installment_value": 120.0,
      "total_amount": 1200.0,
      "original_amount": 1200.0
    },
    "simulation_details": {
      "requested_amount": 1200.0,
      "requested_installments": 10,
      "preferred_method": "credit_card",
      "installments_summary": "10x de R$ 120,00"
    }
  }
}

Explicação dos Campos

• pix / boleto: Retornam sempre o valor integral para pagamento à vista (1 parcela).
• credit_card: Calcula o valor de cada parcela dividindo o montante total pelo número de parcelas informado.
• installment_value: Valor individual de cada parcela.
• total_amount: Soma total a ser paga (pode variar levemente em relação ao original devido a arredondamentos de parcelas).
• original_amount: O valor base enviado para a simulação.
• preferred_method: Sugestão do sistema baseada no número de parcelas (Pix para 1x, Cartão para >1x).
• installments_summary: Resumo amigável em texto do parcelamento solicitado.

---

Exemplos de Erro

422 Unprocessable Entity (Validação)

{
  "message": "The installments field must be at least 1.",
  "errors": {
    "installments": [
      "O número mínimo de parcelas é 1."
    ]
  }
}

401 Unauthorized

{
  "message": "Unauthenticated."
}