{ "openapi": "3.1.0", "info": {"title": "InvestMoz Simulation Execution API", "version": "1.0.0", "description": "Indicative arithmetic scenarios. Rates and reductions are user supplied, not legal rates or eligibility decisions."}, "servers": [{"url": "/api/v1"}], "paths": { "/simulation-drafts": { "post": {"summary": "Create an encrypted, versioned simulator form draft", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}, {"$ref": "#/components/parameters/SimulationToken"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SimulationFormDraft"}}}}, "responses": {"201": {"description": "Created with ETag"}, "200": {"description": "Idempotent replay"}, "409": {"description": "Draft exists or key reused with a different payload"}, "422": {"description": "Invalid draft field"}}} }, "/simulation-drafts/current": { "get": {"summary": "Read the current user's or anonymous token's draft", "parameters": [{"$ref": "#/components/parameters/SimulationToken"}], "responses": {"200": {"description": "Draft snapshot and ETag; personal fields are decrypted only for its owner"}}} }, "/simulation-drafts/{id}": { "get": {"summary": "Read an owned draft", "parameters": [{"$ref": "#/components/parameters/Id"}, {"$ref": "#/components/parameters/SimulationToken"}], "responses": {"200": {"description": "Draft snapshot and ETag"}, "404": {"description": "Draft inaccessible"}}}, "put": {"summary": "Autosave an owned draft with optimistic locking", "parameters": [{"$ref": "#/components/parameters/Id"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/SimulationToken"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SimulationFormDraft"}}}}, "responses": {"200": {"description": "Saved with new ETag and snapshot hash"}, "412": {"description": "Stale draft version"}, "422": {"description": "Invalid draft field"}}}, "delete": {"summary": "Soft-delete an owned draft", "parameters": [{"$ref": "#/components/parameters/Id"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/SimulationToken"}], "responses": {"204": {"description": "Deleted"}, "412": {"description": "Stale draft version"}}} }, "/questionnaires/{code}": {"get": {"summary": "Read the published Portuguese questionnaire version", "parameters": [{"name": "code", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "Published questionnaire and stable version", "headers": {"ETag": {"schema": {"type": "string"}}}}, "404": {"description": "No published current version"}}}}, "/simulations": { "post": { "summary": "Create a traceable simulation", "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}, {"$ref": "#/components/parameters/SimulationToken"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SimulationInput"}}}}, "responses": {"202": {"description": "Execution queued", "headers": {"ETag": {"schema": {"type": "string"}}, "Location": {"schema": {"type": "string"}}}}, "200": {"description": "Idempotent replay"}, "409": {"description": "Key reused with a different payload"}, "422": {"description": "Invalid input or missing anonymous token"}, "428": {"description": "Idempotency-Key required"}} } }, "/simulations/{id}": { "get": {"summary": "Read a simulation and its snapshots", "parameters": [{"$ref": "#/components/parameters/Id"}, {"$ref": "#/components/parameters/SimulationToken"}], "responses": {"200": {"description": "Simulation", "headers": {"ETag": {"schema": {"type": "string"}}}}, "404": {"description": "Missing or outside authorized scope"}}} }, "/simulations/{id}/scenarios/{scenarioId}": { "patch": { "summary": "Update a scenario with optimistic concurrency", "parameters": [{"$ref": "#/components/parameters/Id"}, {"$ref": "#/components/parameters/ScenarioId"}, {"$ref": "#/components/parameters/IfMatch"}, {"$ref": "#/components/parameters/SimulationToken"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/UpdateScenarioInput"}}}}, "responses": {"202": {"description": "Updated; re-execution queued"}, "403": {"description": "Edit not authorized"}, "404": {"description": "Simulation inaccessible"}, "412": {"description": "Stale ETag"}, "428": {"description": "If-Match required"}, "422": {"description": "Invalid input"}} } }, "/simulations/{id}/reports/{reportId}": { "get": {"summary": "Read an immutable report snapshot", "parameters": [{"$ref": "#/components/parameters/Id"}, {"$ref": "#/components/parameters/ReportId"}, {"$ref": "#/components/parameters/SimulationToken"}], "responses": {"200": {"description": "Report snapshot and hash"}, "404": {"description": "Report inaccessible"}}} } }, "components": { "parameters": { "Id": {"name": "id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, "ScenarioId": {"name": "scenarioId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, "ReportId": {"name": "reportId", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, "IdempotencyKey": {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 16, "maxLength": 128}}, "SimulationToken": {"name": "X-Simulation-Token", "in": "header", "required": false, "description": "Required for anonymous access. Client generated; only an HMAC hash is stored.", "schema": {"type": "string", "minLength": 32, "maxLength": 256}}, "IfMatch": {"name": "If-Match", "in": "header", "required": true, "description": "Strong ETag; absent returns 428, stale returns 412.", "schema": {"type": "string"}} }, "schemas": { "SimulationInput": {"type": "object", "additionalProperties": false, "required": ["base", "rate", "reduction"], "properties": {"base": {"type": "number", "minimum": 0, "description": "User input; no currency is inferred."}, "rate": {"type": "number", "minimum": 0, "maximum": 100, "description": "User scenario rate; not an official rate."}, "reduction": {"type": "number", "minimum": 0, "maximum": 100, "description": "User supplied scenario reduction; no default is applied."}, "organization_id": {"type": "string", "format": "uuid", "description": "Optional; requires admin, manager or officer membership."}}}, "SimulationFormDraft": {"type": "object", "additionalProperties": false, "required": ["personal_snapshot", "economic_snapshot"], "properties": {"personal_snapshot": {"type": "object", "description": "Allowlisted personal fields, encrypted at rest; only owner/token can read."}, "economic_snapshot": {"type": "object", "required": ["purpose"], "description": "Allowlisted economic/form fields, encrypted at rest; rates remain user-supplied."}}}, "UpdateScenarioInput": {"type": "object", "additionalProperties": false, "required": ["label", "base", "rate", "reduction"], "properties": {"label": {"type": "string", "minLength": 1, "maxLength": 100}, "base": {"type": "number", "minimum": 0}, "rate": {"type": "number", "minimum": 0, "maximum": 100}, "reduction": {"type": "number", "minimum": 0, "maximum": 100, "description": "User supplied scenario reduction; no default is applied."}}} } } }