# Simulate a loan

Simulates a loan scenario for a specific credit offer. The customer can
simulate multiple times with different amounts and terms before committing.
The simulation is synchronous and returns installment amounts, fees, and total cost. The result
is persisted and can be referenced when creating the loan via simulation_id.
Only the latest simulation is valid for contracting (Last Write Record).

Endpoint: POST /credit-offers/{credit_offer_id}/simulations
Version: 2026-03-01
Security: bearerAuth

## Path parameters:

  - `credit_offer_id` (string, required)
    Example: "co_550e8400e29b41d4a716446655440000"

## Header parameters:

  - `Idempotency-Key` (string)
    Unique string for idempotent POST requests. Cached for 24 hours.

## Request fields (application/json):

  - `requested_amount` (string, required)
    Requested loan amount
    Example: "25000.00"

  - `installment_count` (integer, required)
    Number of installments for the simulation
    Example: 12

## Response 201 fields (application/json):

  - `id` (string, required)

  - `credit_offer_id` (string, required)

  - `requested_amount` (string, required)
    Amount requested by the partner
    Example: "25000.00"

  - `amount` (string, required)
    Net amount to be received by the customer
    Example: "24250.00"

  - `interest_amount` (string, required)
    Total interest amount
    Example: "2750.00"

  - `fees_amount` (string, required)
    Total fees amount
    Example: "300.00"

  - `iof_amount` (string, required)
    IOF tax amount
    Example: "450.00"

  - `total_loan_amount` (string, required)
    Total loan amount (principal + interest + fees + IOF)
    Example: "27500.00"

  - `interest_percentage` (number, required)
    Monthly interest rate (percentage)
    Example: 3.5

  - `cet_percentage` (number, required)
    Total effective cost (annual percentage)
    Example: 4.12

  - `number_of_installments` (integer, required)
    Number of installments
    Example: 12

  - `installments_value` (string, required)
    Amount per installment
    Example: "2291.67"

  - `first_due_date` (string, required)
    Due date of the first installment
    Example: "2026-04-03"

  - `created_at` (string, required)

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the error type

  - `title` (string, required)
    Short, human-readable summary of the problem type

  - `status` (integer, required)
    HTTP status code

  - `detail` (string, required)
    Human-readable explanation specific to this occurrence

  - `instance` (string)
    URI identifying this specific occurrence

  - `code` (string)
    Machine-readable subtype code

  - `param` (string)
    The request parameter that caused the error

  - `errors` (array)
    Field-level validation errors

  - `errors.param` (string, required)

  - `errors.detail` (string, required)

  - `errors.code` (string)

## Response 401 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the error type

  - `title` (string, required)
    Short, human-readable summary of the problem type

  - `status` (integer, required)
    HTTP status code

  - `detail` (string, required)
    Human-readable explanation specific to this occurrence

  - `instance` (string)
    URI identifying this specific occurrence

  - `code` (string)
    Machine-readable subtype code

  - `param` (string)
    The request parameter that caused the error

  - `errors` (array)
    Field-level validation errors

  - `errors.param` (string, required)

  - `errors.detail` (string, required)

  - `errors.code` (string)

## Response 404 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the error type

  - `title` (string, required)
    Short, human-readable summary of the problem type

  - `status` (integer, required)
    HTTP status code

  - `detail` (string, required)
    Human-readable explanation specific to this occurrence

  - `instance` (string)
    URI identifying this specific occurrence

  - `code` (string)
    Machine-readable subtype code

  - `param` (string)
    The request parameter that caused the error

  - `errors` (array)
    Field-level validation errors

  - `errors.param` (string, required)

  - `errors.detail` (string, required)

  - `errors.code` (string)

## Response 422 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the error type

  - `title` (string, required)
    Short, human-readable summary of the problem type

  - `status` (integer, required)
    HTTP status code

  - `detail` (string, required)
    Human-readable explanation specific to this occurrence

  - `instance` (string)
    URI identifying this specific occurrence

  - `code` (string)
    Machine-readable subtype code

  - `param` (string)
    The request parameter that caused the error

  - `errors` (array)
    Field-level validation errors

  - `errors.param` (string, required)

  - `errors.detail` (string, required)

  - `errors.code` (string)

## Response 429 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the error type

  - `title` (string, required)
    Short, human-readable summary of the problem type

  - `status` (integer, required)
    HTTP status code

  - `detail` (string, required)
    Human-readable explanation specific to this occurrence

  - `instance` (string)
    URI identifying this specific occurrence

  - `code` (string)
    Machine-readable subtype code

  - `param` (string)
    The request parameter that caused the error

  - `errors` (array)
    Field-level validation errors

  - `errors.param` (string, required)

  - `errors.detail` (string, required)

  - `errors.code` (string)

## Response 500 fields (application/problem+json):

  - `type` (string, required)
    URI identifying the error type

  - `title` (string, required)
    Short, human-readable summary of the problem type

  - `status` (integer, required)
    HTTP status code

  - `detail` (string, required)
    Human-readable explanation specific to this occurrence

  - `instance` (string)
    URI identifying this specific occurrence

  - `code` (string)
    Machine-readable subtype code

  - `param` (string)
    The request parameter that caused the error

  - `errors` (array)
    Field-level validation errors

  - `errors.param` (string, required)

  - `errors.detail` (string, required)

  - `errors.code` (string)