Files
Investidor-V2/docs/investmoz/simulations/rule-governance-openapi.json
T
nala e65cb26901
tests / ci (push) Canceled after 0s
varias alteracoes
2026-10-06 14:50:12 +02:00

53 lines
5.5 KiB
JSON

{
"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}}}
}
}
}