{
  "openapi": "3.1.0",
  "info": {
    "title": "MasteryHive Reconciliation \u2014 Reversals (platform)",
    "version": "0.1.0",
    "description": "Platform-operated. Local servers only."
  },
  "servers": [
    {
      "url": "http://localhost:8000/v1",
      "description": "Local mesh placeholder \u2014 replace host; keep /v1 prefix. Cloud bases require owner decision."
    }
  ],
  "paths": {
    "/": {
      "get": {
        "summary": "Home",
        "operationId": "home__get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "summary": "Health",
        "operationId": "health_health_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        }
      }
    },
    "/reversals/pipeline/background": {
      "post": {
        "tags": [
          "Reversals"
        ],
        "summary": "Run GL reversals then chain to recon-engine (called by ingestion after ETL)",
        "operationId": "run_pipeline_reversals_pipeline_background_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PipelineRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/reversals/gl-reversals/background": {
      "post": {
        "tags": [
          "Reversals"
        ],
        "summary": "Detect and process GL reversal pairs",
        "operationId": "gl_reversals_reversals_gl_reversals_background_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GLReversalRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/reversals/reprocess-cross-month/background": {
      "post": {
        "tags": [
          "Reversals"
        ],
        "summary": "Re-run matching on previously unmatched cross-month transactions",
        "operationId": "reprocess_cross_month_reversals_reprocess_cross_month_background_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReprocessRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BankService": {
        "type": "string",
        "enum": [
          "transfers",
          "pos",
          "ussd",
          "bill_payments",
          "card_settlement",
          "cash_deposits",
          "pos_deposits",
          "atm",
          "nip",
          "other"
        ],
        "title": "BankService",
        "description": "Bank service types"
      },
      "FeeDisplayType": {
        "type": "string",
        "enum": [
          "netted",
          "separate"
        ],
        "title": "FeeDisplayType",
        "description": "Fee display types"
      },
      "FeeType": {
        "type": "string",
        "enum": [
          "fixed",
          "percentage"
        ],
        "title": "FeeType",
        "description": "Fee calculation types"
      },
      "GLReversalRequest": {
        "properties": {
          "session_id": {
            "type": "string",
            "title": "Session Id"
          },
          "tenant_id": {
            "type": "string",
            "title": "Tenant Id"
          },
          "partner_id": {
            "type": "string",
            "title": "Partner Id"
          },
          "branch_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Branch Id"
          },
          "start_date": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Start Date"
          },
          "end_date": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "End Date"
          },
          "month": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Month"
          },
          "year": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Year"
          },
          "max_days_forward": {
            "type": "integer",
            "title": "Max Days Forward",
            "default": 7
          },
          "max_days_backward": {
            "type": "integer",
            "title": "Max Days Backward",
            "default": 7
          }
        },
        "type": "object",
        "required": [
          "session_id",
          "tenant_id",
          "partner_id"
        ],
        "title": "GLReversalRequest"
      },
      "GLType": {
        "type": "string",
        "enum": [
          "income",
          "nip_fee"
        ],
        "title": "GLType",
        "description": "General Ledger types"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "MatchingMethod": {
        "type": "string",
        "enum": [
          "line_by_line",
          "bulk",
          "lump_sum",
          "line_by_line_and_lump_sum"
        ],
        "title": "MatchingMethod",
        "description": "Matching methods for reconciliation"
      },
      "PipelineRequest": {
        "properties": {
          "session_id": {
            "type": "string",
            "title": "Session Id"
          },
          "tenant_id": {
            "type": "string",
            "title": "Tenant Id"
          },
          "partner_id": {
            "type": "string",
            "title": "Partner Id"
          },
          "branch_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Branch Id"
          },
          "period_start_date": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Period Start Date"
          },
          "period_end_date": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Period End Date"
          },
          "reversal_max_days_forward_search": {
            "type": "integer",
            "title": "Reversal Max Days Forward Search",
            "default": 7
          },
          "reversal_max_days_backward_search": {
            "type": "integer",
            "title": "Reversal Max Days Backward Search",
            "default": 7
          },
          "max_days_forward_search": {
            "type": "integer",
            "title": "Max Days Forward Search",
            "default": 0
          },
          "max_days_backward_search": {
            "type": "integer",
            "title": "Max Days Backward Search",
            "default": 0
          },
          "msc_rate": {
            "type": "number",
            "title": "Msc Rate",
            "default": 0.0
          },
          "amount_tolerance": {
            "type": "number",
            "title": "Amount Tolerance",
            "default": 0.0
          },
          "charge_min": {
            "type": "number",
            "title": "Charge Min",
            "default": 0.0
          },
          "charge_max": {
            "type": "number",
            "title": "Charge Max",
            "default": 0.0
          },
          "search_mode": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Search Mode"
          },
          "matching_method": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Matching Method"
          },
          "customer_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Customer Type"
          },
          "reconciliation_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Reconciliation Type"
          },
          "ingress_task_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Ingress Task Id"
          },
          "records_create_task_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Records Create Task Id"
          },
          "gl_reversal_task_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Gl Reversal Task Id"
          },
          "matched_records_task_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Matched Records Task Id"
          },
          "reconciliation_task_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Reconciliation Task Id"
          },
          "summary_task_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Summary Task Id"
          },
          "exclude_debits_from_rate": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Exclude Debits From Rate",
            "default": true
          },
          "exception_analysis_enabled": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Exception Analysis Enabled",
            "default": true
          },
          "gl_file_url": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Gl File Url"
          },
          "bank_file_url": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Bank File Url"
          },
          "on_existing_action": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "On Existing Action",
            "default": "overwrite"
          },
          "is_switch": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Is Switch",
            "default": false
          },
          "custodian_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Custodian Id"
          },
          "custodian_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Custodian Name"
          }
        },
        "type": "object",
        "required": [
          "session_id",
          "tenant_id",
          "partner_id"
        ],
        "title": "PipelineRequest",
        "description": "Full pipeline request: reversals \u2192 recon-engine. Called by ingestion after ETL."
      },
      "ReconciliationRuleCreate": {
        "properties": {
          "bank_service": {
            "$ref": "#/components/schemas/BankService",
            "description": "Bank service type"
          },
          "min_amount": {
            "type": "number",
            "title": "Min Amount",
            "description": "Minimum transaction amount",
            "default": 0.0
          },
          "max_amount": {
            "type": "number",
            "title": "Max Amount",
            "description": "Maximum transaction amount",
            "default": 0.0
          },
          "amount": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Amount",
            "description": "Rule amount"
          },
          "fee_type": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FeeType"
              },
              {
                "type": "null"
              }
            ],
            "description": "Fee calculation type"
          },
          "rule_definitions": {
            "items": {
              "$ref": "#/components/schemas/RuleDefinitionCreate"
            },
            "type": "array",
            "minItems": 1,
            "title": "Rule Definitions",
            "description": "List of rule definitions"
          }
        },
        "type": "object",
        "required": [
          "bank_service",
          "rule_definitions"
        ],
        "title": "ReconciliationRuleCreate",
        "description": "Schema for creating reconciliation rules"
      },
      "ReconciliationTemplateCreate": {
        "properties": {
          "service": {
            "$ref": "#/components/schemas/ServiceType",
            "description": "Service type for reconciliation"
          },
          "is_reversal": {
            "type": "boolean",
            "title": "Is Reversal",
            "description": "Perform GL Reversal",
            "default": true
          },
          "matching_method": {
            "$ref": "#/components/schemas/MatchingMethod",
            "description": "Matching method for reconciliation"
          },
          "max_days_backward_search": {
            "type": "integer",
            "minimum": 0.0,
            "title": "Max Days Backward Search",
            "description": "Maximum days to search backward for matches"
          },
          "max_days_forward_search": {
            "type": "integer",
            "minimum": 0.0,
            "title": "Max Days Forward Search",
            "description": "Maximum days to search forward for matches"
          },
          "reversal_max_days_backward_search": {
            "type": "integer",
            "minimum": 0.0,
            "title": "Reversal Max Days Backward Search",
            "description": "Maximum days to search backward for reversals"
          },
          "reversal_max_days_forward_search": {
            "type": "integer",
            "minimum": 0.0,
            "title": "Reversal Max Days Forward Search",
            "description": "Maximum days to search forward for reversals"
          },
          "search_mode": {
            "type": "string",
            "title": "Search Mode",
            "description": "Search Mode"
          },
          "fee_display_type": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FeeDisplayType"
              },
              {
                "type": "null"
              }
            ],
            "description": "How fees should be displayed: 'netted' (combined with transaction) or 'separate' (shown separately)"
          },
          "rules": {
            "items": {
              "$ref": "#/components/schemas/ReconciliationRuleCreate"
            },
            "type": "array",
            "title": "Rules",
            "description": "List of reconciliation rules"
          }
        },
        "type": "object",
        "required": [
          "service",
          "matching_method",
          "max_days_backward_search",
          "max_days_forward_search",
          "reversal_max_days_backward_search",
          "reversal_max_days_forward_search"
        ],
        "title": "ReconciliationTemplateCreate",
        "description": "Schema for creating reconciliation templates",
        "example": {
          "is_draft": false,
          "matching_method": "line_by_line",
          "max_days_backward_search": 7,
          "max_days_forward_search": 3,
          "name": "Card Settlement Template",
          "reversal_max_days_backward_search": 14,
          "reversal_max_days_forward_search": 7,
          "rules": [
            {
              "amount": 5000.0,
              "bank_service": "pos",
              "fee_type": "percentage",
              "max_amount": 10000.0,
              "min_amount": 0.0,
              "rule_definitions": [
                {
                  "amount": 100.0,
                  "entry": "debit",
                  "gl_type": "income",
                  "split_type": "fixed"
                },
                {
                  "amount": 2.5,
                  "entry": "credit",
                  "gl_type": "nip_fee",
                  "split_type": "percentage"
                }
              ]
            },
            {
              "amount": 25000.0,
              "bank_service": "transfers",
              "fee_type": "fixed",
              "max_amount": 50000.0,
              "min_amount": 0.0,
              "rule_definitions": [
                {
                  "amount": 50.0,
                  "entry": "debit",
                  "gl_type": "income",
                  "split_type": "fixed"
                }
              ]
            }
          ],
          "service": "card_settlement"
        }
      },
      "ReprocessRequest": {
        "properties": {
          "session_id": {
            "type": "string",
            "title": "Session Id"
          },
          "tenant_id": {
            "type": "string",
            "title": "Tenant Id"
          },
          "partner_id": {
            "type": "string",
            "title": "Partner Id"
          },
          "branch_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Branch Id"
          },
          "period_start_date": {
            "type": "string",
            "title": "Period Start Date"
          },
          "period_end_date": {
            "type": "string",
            "title": "Period End Date"
          },
          "template": {
            "$ref": "#/components/schemas/ReconciliationTemplateCreate"
          },
          "months_back": {
            "type": "integer",
            "title": "Months Back",
            "default": 1
          }
        },
        "type": "object",
        "required": [
          "session_id",
          "tenant_id",
          "partner_id",
          "period_start_date",
          "period_end_date",
          "template"
        ],
        "title": "ReprocessRequest"
      },
      "RuleDefinitionCreate": {
        "properties": {
          "gl_type": {
            "$ref": "#/components/schemas/GLType",
            "description": "General Ledger type"
          },
          "amount": {
            "type": "number",
            "title": "Amount",
            "description": "Amount for the rule definition"
          },
          "entry": {
            "type": "string",
            "title": "Entry",
            "description": "Entry type (debit/credit)"
          },
          "split_type": {
            "$ref": "#/components/schemas/SplitType",
            "description": "Split calculation type"
          },
          "msc_rate": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Msc Rate",
            "description": "MSC rate (e.g. 0.0025 = 0.25%)"
          }
        },
        "type": "object",
        "required": [
          "gl_type",
          "amount",
          "entry",
          "split_type"
        ],
        "title": "RuleDefinitionCreate",
        "description": "Schema for creating rule definitions"
      },
      "ServiceType": {
        "type": "string",
        "enum": [
          "card_settlement",
          "transfers",
          "cash_deposits",
          "pos_deposits",
          "pos",
          "ussd",
          "bill_payments",
          "atm",
          "nip",
          "other"
        ],
        "title": "ServiceType",
        "description": "Service types for reconciliation templates"
      },
      "SplitType": {
        "type": "string",
        "enum": [
          "fixed",
          "percentage"
        ],
        "title": "SplitType",
        "description": "Split calculation types"
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      }
    }
  }
}