290 lines
11 KiB
JSON
290 lines
11 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
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|