53 lines
5.5 KiB
JSON
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}}}
|
|
}
|
|
}
|
|
}
|