Skip to content

Sandbox Simulate

In the sandbox there is no real lender, no live Kairos/GRENKE call, and no DocuSign API. POST /api/sandbox/financing_cases/{id}/simulate drives a financing case you own into a named state (or creates real document-request entities) so you can test every branch of your integration. It is available only when API_ENVIRONMENT=sandbox and you authenticate with a Sandbox API key. Outside sandbox the route responds 404 and applies no transition.

Endpoint & auth

POST /api/sandbox/financing_cases/{id}/simulate

Send JSON {"scenario":"<value>","data":{…}}. scenario is required; data is optional unless the scenario table below marks fields as required. Authenticate with your Sandbox API key in the X-Api-Key header. The case {id} must belong to the partner of that key.

The legacy POST /api/sandbox/financing_cases/{id}/finance-decision endpoint remains available and unchanged for the simple accepted/rejected solvency branch. Prefer simulate when you need document requests, contract places, e-signature envelope states, or reset.

Scenario table

Source of truth for scenario values: src/Entity/Enum/SandboxScenario.php. Required data and behaviour: SandboxSimulateProcessor / SandboxSimulationService and the handlers under src/Service/Sandbox/Scenario/. If the enum or a handler gains a new case, update this table in the same change.

Sandbox simulate scenarios (SandboxScenario enum)
Scenario Required data Notes
finance_review — Moves quote into finance review (skips live financing submission).
manual_finance_review — Starts manual finance review.
finance_accepted — Same path as finance-decision accepted (incl. active financing response for e-signature).
finance_rejected rejectionReason (optional string) Same path as finance-decision rejected; reason exposed on GET financing case.
canceled — Same cancellation rules as POST /financing_cases/{id}/cancel.
information_requested question (string) or items[{question}] Creates RequestedInformation; answerable via the regular information respond endpoint.
requested_document label + category (or items[{label,category}]) Financing-stage document categories only; invalid category → 422.
requested_fill_and_return label + category (or items[{label,category}]) Fill-and-return categories: self_disclosure_template, default_guarantee.
change_requested message (string, required) Quote must be in_review; otherwise 422.
document_rejected documentId (int, required); reason (optional) PENDING_REVIEW FinancingDocument on this case; foreign id → 404; re-opens linked request.
upload_rejected_type documentId (int, required) Open RequestedDocument / RequestedFillAndReturn; returns prod MIME-reject HTTP 400 shape.
upload_rejected_size documentId (int, required) Same as type, with size-reject HTTP 400 shape.
wait_for_signing — Contract SM place; creates Contract at wait_for_signing when missing (no DocuSign).
signed — Attaches idempotent SIGNED_CONTRACT FinancingDocument (listable + PDF downloadable).
post_processing_required — Contract SM place.
delivery_approved — Contract SM place.
invoice_checked — Contract SM place.
completed — Requires a contract number else 422.
signature_sent — Local DocuSignEnvelope → sent (Contract at wait_for_signing; created when missing).
signature_signed — Envelope → signed.
signature_declined reason (optional string) Envelope → declined.
reset targetStatus (string, required) Rewinds case; does not delete. Allowed targets listed in OpenAPI / SandboxResetTargetStatus.

Unreachable transitions and missing required data return 422 (message names current/desired status or lists allowed values). Created request entities have no sandbox marker in the payload.

Copy-paste examples

Replace the financing-case id and YOUR_SANDBOX_API_KEY. All samples include a JSON body.

1. Accept financing

curl -X POST 'https://sandbox.partner.miete24.com/api/sandbox/financing_cases/019e964c-fb93-73a6-a672-254c170c72d9/simulate' \
  -H 'X-Api-Key: YOUR_SANDBOX_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"scenario":"finance_accepted","data":{}}'

2. Reject financing with reason

curl -X POST 'https://sandbox.partner.miete24.com/api/sandbox/financing_cases/019e964c-fb93-73a6-a672-254c170c72d9/simulate' \
  -H 'X-Api-Key: YOUR_SANDBOX_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"scenario":"finance_rejected","data":{"rejectionReason":"Insufficient credit history"}}'

3. Request a document

curl -X POST 'https://sandbox.partner.miete24.com/api/sandbox/financing_cases/019e964c-fb93-73a6-a672-254c170c72d9/simulate' \
  -H 'X-Api-Key: YOUR_SANDBOX_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"scenario":"requested_document","data":{"label":"Handelsregisterauszug","category":"business_registration"}}'

4. Reset to finance review

curl -X POST 'https://sandbox.partner.miete24.com/api/sandbox/financing_cases/019e964c-fb93-73a6-a672-254c170c72d9/simulate' \
  -H 'X-Api-Key: YOUR_SANDBOX_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"scenario":"reset","data":{"targetStatus":"finance_review"}}'

Responses

Responses for POST /api/sandbox/financing_cases/{id}/simulate
Status When
204 Scenario applied (empty body).
400 upload_rejected_type / upload_rejected_size — production upload-error payload (not a special sandbox shape).
401 Missing or invalid API key.
403 Financing case belongs to another partner.
404 Unknown case id, or API_ENVIRONMENT is not sandbox (endpoint inactive).
422 Unknown scenario, missing/invalid required data, invalid category, or unreachable transition.

Not the Calculate sandboxScenario field

This page is about POST /api/sandbox/financing_cases/{id}/simulate and the SandboxScenario enum. Separately, POST /api/calculate and POST /api/calculate/estimate accept an optional body field sandboxScenario from a different enum (CalculationSandboxScenario, PH-1017). The only value is calculation_not_possible, which forces the empty-calculation failure shape. That field does not drive financing-case states and this simulate endpoint does not accept it. Outside API_ENVIRONMENT=sandbox the Calculate field is rejected with 422.

Full OpenAPI for both sandbox surfaces → Sandbox reference

What's next