{ "openapi": "3.1.0", "info": { "title": "InvestMoz Tax Rule Governance API", "version": "0.1.0", "description": "Management-only rule version workflow. Records are not read by the simulation engine; no fiscal parameters are activated by this API." }, "servers": [{"url": "/api/v2/investment/admin"}], "security": [{"webSession": []}], "paths": { "/tax-rules": { "get": { "summary": "List rule versions for designated governance users", "parameters": [ {"name": "rule_code", "in": "query", "schema": {"type": "string", "maxLength": 64}}, {"name": "component", "in": "query", "schema": {"$ref": "#/components/schemas/Component"}}, {"name": "scope_key", "in": "query", "schema": {"type": "string", "maxLength": 160}}, {"name": "status", "in": "query", "schema": {"$ref": "#/components/schemas/Status"}}, {"name": "per_page", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100}} ], "responses": {"200": {"description": "Paginated rule versions"}, "403": {"description": "Role or MFA required"}} }, "post": { "summary": "Create a draft version (editor role)", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RuleVersionInput"}}}}, "responses": {"201": {"description": "Draft saved with version_no 1"}, "403": {"description": "Editor role and MFA required"}, "422": {"description": "Invalid source, fields, or scope"}} } }, "/tax-rules/{id}": { "get": {"summary": "Read a rule version and its governance state", "parameters": [{"$ref": "#/components/parameters/Id"}], "responses": {"200": {"description": "Private governance record"}, "404": {"description": "Not found"}}}, "put": {"summary": "Edit the author's draft with optimistic locking", "parameters": [{"$ref": "#/components/parameters/Id"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"allOf": [{"$ref": "#/components/schemas/RuleVersionInput"}, {"type": "object", "required": ["version_no"], "properties": {"version_no": {"type": "integer", "minimum": 1}}}]}}}}, "responses": {"200": {"description": "Updated draft"}, "403": {"description": "Only author/editor may change own draft"}, "409": {"description": "Stale version"}}} }, "/tax-rules/{id}/{action}": { "post": { "summary": "Advance a rule through submit, review, reject, approve, publish, suspend, or archive", "parameters": [{"$ref": "#/components/parameters/Id"}, {"name": "action", "in": "path", "required": true, "schema": {"type": "string", "enum": ["submit", "review", "reject", "approve", "publish", "suspend", "archive"]}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Transition"}}}}, "responses": {"200": {"description": "Transition recorded with append-only snapshot"}, "403": {"description": "Role segregation denied transition"}, "409": {"description": "Stale version or published period overlap"}, "422": {"description": "Invalid state or unavailable legal source"}} } } }, "components": { "securitySchemes": {"webSession": {"type": "apiKey", "in": "cookie", "name": "investmoz_session", "description": "Verified portal manager, confirmed MFA, and explicit role allowlist are all required."}}, "parameters": {"Id": {"name": "id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}}, "schemas": { "Component": {"type": "string", "enum": ["IRPC", "IVA", "ISPC", "IRPS", "INSS", "RETENCOES", "DIREITOS_ADUANEIROS", "ICE"]}, "Status": {"type": "string", "enum": ["draft", "submitted", "reviewed", "rejected", "approved", "published", "suspended", "archived"]}, "RuleVersionInput": {"type": "object", "additionalProperties": false, "required": ["rule_code", "rule_version", "component", "scope_key", "valid_from", "legal_source_id", "source_sha256", "rule_definition", "parameters", "rounding_policy"], "properties": {"rule_code": {"type": "string", "pattern": "^[A-Z0-9][A-Z0-9._-]{2,63}$"}, "rule_version": {"type": "integer", "minimum": 1}, "component": {"$ref": "#/components/schemas/Component"}, "scope_key": {"type": "string", "minLength": 2, "maxLength": 160}, "valid_from": {"type": "string", "format": "date"}, "valid_until": {"type": ["string", "null"], "format": "date"}, "legal_source_id": {"type": "string", "format": "uuid"}, "source_sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Hash declared by the editor; official exemplar verification remains an approval task."}, "rule_definition": {"type": "object", "description": "Versioned declarative AST; a parameter update may preserve the same AST."}, "parameters": {"type": "object", "description": "Versioned values approved with the rule version; each DSL parameter has value, unit and conditions. No values are seeded.", "additionalProperties": {"type": "object", "required": ["value", "unit", "conditions"], "properties": {"value": {"oneOf": [{"type": "string"}, {"type": "integer"}]}, "unit": {"type": "string"}, "conditions": {"type": "object"}}}}, "rounding_policy": {"type": "object", "description": "Versioned with the rule and must be approved."}}}, "Transition": {"type": "object", "additionalProperties": false, "required": ["version_no", "evidence"], "properties": {"version_no": {"type": "integer", "minimum": 1}, "evidence": {"type": "string", "minLength": 20, "maxLength": 2000}}} } } }