{
  "openapi": "3.1.0",
  "info": {
    "title": "Finora Business API",
    "version": "1.0.0",
    "description": "REST API for Nigerian accounting, invoicing, tax compliance, and bank reconciliation. The same API that powers the Finora Business mobile app is available to every Premium subscriber.",
    "contact": {
      "name": "Finora Business Developer Support",
      "url": "https://finorabusiness.com/contact",
      "email": "hello@finorabusiness.com"
    },
    "license": {
      "name": "Finora Business API Terms",
      "url": "https://finorabusiness.com/terms-of-use"
    }
  },
  "servers": [
    {
      "url": "https://api.finorabusiness.com/v1",
      "description": "Production (branded domain)"
    },
    {
      "url": "https://us-central1-finora-production.cloudfunctions.net/finoraAPI/v1",
      "description": "Production (Cloud Functions direct)"
    },
    {
      "url": "https://us-central1-finora-staging-843fe.cloudfunctions.net/finoraAPI/v1",
      "description": "Staging"
    }
  ],
  "tags": [
    {
      "name": "Digital Officer / AI",
      "description": "Proactive financial health alerts, rule-based product recommendations, and a natural-language query endpoint over the business's financials."
    },
    {
      "name": "Branch & Regional Analytics",
      "description": "Management dashboards at branch, regional, and national level, plus officer leaderboards and sector benchmarks."
    },
    {
      "name": "API Key Management",
      "description": "Create, list, revoke, and inspect usage of API keys programmatically."
    },
    {
      "name": "Bank Transactions",
      "description": "Push bank transactions, match them to accounting entries, and reconcile balances."
    },
    {
      "name": "Bills & Payments",
      "description": "Supplier invoices with staged payment, WHT on payment, and void support."
    },
    {
      "name": "Capital Contributions",
      "description": "Record owner or investor funding into the business. Posts to Share Capital automatically."
    },
    {
      "name": "Chart of Accounts",
      "description": "The list of ledger accounts (revenue, expenses, assets, liabilities, equity) with running balances."
    },
    {
      "name": "CIT Return",
      "description": "Annual Company Income Tax computation. Dashboard-only today; API export is on the roadmap."
    },
    {
      "name": "Credit Notes",
      "description": "Sales-side corrections with their own GL reversal and NRS 380 transmission. Posted credit notes are terminal — to correct one, issue a debit note."
    },
    {
      "name": "Customers",
      "description": "Full CRUD plus find-or-create and search. PII is encrypted at rest and decrypted for API responses."
    },
    {
      "name": "Debit Notes",
      "description": "Internal-only corrections. Supplier-side claims against a bill (returns, disputes), customer-side AR increases, and the formal correction path for a posted credit note."
    },
    {
      "name": "Document Generation",
      "description": "Generate PDF and Excel documents for invoices, receipts, quotations, VAT returns, WHT certificates, and payslips."
    },
    {
      "name": "Employees",
      "description": "Employee directory with activation, deactivation, and PII encryption."
    },
    {
      "name": "Enterprise Management",
      "description": "Provision and deprovision businesses under an enterprise account, inspect API usage, and manage the shared wallet."
    },
    {
      "name": "Expenses",
      "description": "Capture business spend with VAT, WHT, supplier, and category. Void creates a reversing GL entry."
    },
    {
      "name": "Fixed Assets",
      "description": "Register, depreciate, and dispose of fixed assets. Monthly depreciation posts automatically."
    },
    {
      "name": "Business Intelligence",
      "description": "Composite business health score (0–1000), detailed health analysis, cross-sell signals, churn risk, and cash-flow forecasts."
    },
    {
      "name": "Invoices",
      "description": "Create, list, fetch, and update sales invoices with automatic GL posting."
    },
    {
      "name": "Journal Entries",
      "description": "Inspect the double-entry audit trail. Manual JEs can be posted and reversed via API."
    },
    {
      "name": "Loans",
      "description": "Loan accounts with disbursement and repayment tracking. GL posts automatically."
    },
    {
      "name": "Account Officers",
      "description": "Relationship manager portal — portfolio, aggregate summary, alerts, cross-sell pipeline, and officer scorecards."
    },
    {
      "name": "PAYE Return",
      "description": "Monthly employee payroll tax remittance. Generated by payroll runs. API export is on the roadmap."
    },
    {
      "name": "Payments & Collections",
      "description": "Generate hosted payment links for invoices and create NFC tap-to-pay sessions. Auto-reconciles to the invoice on completion."
    },
    {
      "name": "Payroll & Payslips",
      "description": "Run payroll, list payroll runs, fetch payslips. PAYE computed on the 2025 Nigerian tax bands."
    },
    {
      "name": "Petty Cash",
      "description": "Requisition, approval, disbursement, and retirement workflow with auto GL posting."
    },
    {
      "name": "Products",
      "description": "Inventory catalogue with VAT categories and stock tracking."
    },
    {
      "name": "Quotations",
      "description": "Sales proposals with a full life cycle — send, accept, decline, and convert to invoice."
    },
    {
      "name": "Receipts",
      "description": "Record payments against invoices, or log cash sales. GL and invoice status update automatically."
    },
    {
      "name": "Reports",
      "description": "P&L, Balance Sheet, Trial Balance, Cash Flow, AR/AP aging, Dashboard summary. All read-only."
    },
    {
      "name": "Smart Loans",
      "description": "Bank-partner lending module — product catalog, eligibility checks, applications, disbursement/repayment sync, covenant monitoring."
    },
    {
      "name": "Suppliers",
      "description": "Vendor directory for bills, expenses, and procurement. PII encrypted at rest, TIN verification supported."
    },
    {
      "name": "Tax & Compliance",
      "description": "Nigerian tax compliance status and period tax summaries (VAT, WHT, CIT, PAYE)."
    },
    {
      "name": "VAT Return",
      "description": "Export the monthly Value Added Tax return (PDF + Excel) ready for FIRS e-filing."
    },
    {
      "name": "Webhooks",
      "description": "Receive HTTP callbacks when things happen in Finora Business. Signed, retried, and scoped per event type."
    },
    {
      "name": "WHT Certificates",
      "description": "Issue Withholding Tax certificates to suppliers. PDF export ready to email or print."
    }
  ],
  "paths": {
    "/businesses/{businessId}/ai/health-alerts": {
      "post": {
        "tags": [
          "Digital Officer / AI"
        ],
        "operationId": "post_businesses_By_businessId_ai_health_alerts",
        "summary": "Triggers an analysis of the business's current financial state and generates proactive alerts where issues are detected.",
        "parameters": [
          {
            "name": "businessId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/businesses/{businessId}/ai/recommendations": {
      "get": {
        "tags": [
          "Digital Officer / AI"
        ],
        "operationId": "get_businesses_By_businessId_ai_recommendations",
        "summary": "Rule-based product and action recommendations tailored to the business's financial state.",
        "parameters": [
          {
            "name": "businessId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/businesses/{businessId}/ai/ask": {
      "post": {
        "tags": [
          "Digital Officer / AI"
        ],
        "operationId": "post_businesses_By_businessId_ai_ask",
        "summary": "Accepts a natural-language question about the business's finances and returns an AI-generated answer with supporting data.",
        "parameters": [
          {
            "name": "businessId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/analytics/branches/{branchId}": {
      "get": {
        "tags": [
          "Branch & Regional Analytics"
        ],
        "operationId": "get_analytics_branches_By_branchId",
        "summary": "Branch-level dashboard: officer count, portfolio health distribution, revenue under management, loan penetration, platform adoption, alert-response SLA.",
        "parameters": [
          {
            "name": "branchId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/analytics/branches/{branchId}/officers": {
      "get": {
        "tags": [
          "Branch & Regional Analytics"
        ],
        "operationId": "get_analytics_branches_By_branchId_officers",
        "summary": "All officers in the branch with performance metrics, sorted by engagement score by default.",
        "parameters": [
          {
            "name": "branchId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/analytics/branches/{branchId}/alerts": {
      "get": {
        "tags": [
          "Branch & Regional Analytics"
        ],
        "operationId": "get_analytics_branches_By_branchId_alerts",
        "summary": "Aggregated alerts across all officers in the branch, sorted by severity then recency.",
        "parameters": [
          {
            "name": "branchId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/analytics/branches/{branchId}/cross-sell-pipeline": {
      "get": {
        "tags": [
          "Branch & Regional Analytics"
        ],
        "operationId": "get_analytics_branches_By_branchId_cross_sell_pipeline",
        "summary": "Branch-wide cross-sell pipeline grouped by product with identified / pitched / converted funnel metrics.",
        "parameters": [
          {
            "name": "branchId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/analytics/regions/{regionId}": {
      "get": {
        "tags": [
          "Branch & Regional Analytics"
        ],
        "operationId": "get_analytics_regions_By_regionId",
        "summary": "Aggregate analytics for a region (multiple branches) with per-branch benchmarking.",
        "parameters": [
          {
            "name": "regionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/analytics/national": {
      "get": {
        "tags": [
          "Branch & Regional Analytics"
        ],
        "operationId": "get_analytics_national",
        "summary": "Executive-level dashboard for the entire enterprise — regions, branches, officers, SMEs, portfolio health, product penetration, heat map.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/analytics/national/sector-benchmarks": {
      "get": {
        "tags": [
          "Branch & Regional Analytics"
        ],
        "operationId": "get_analytics_national_sector_benchmarks",
        "summary": "Industry-level benchmarks across the enterprise's SME portfolio.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/api-keys": {
      "get": {
        "tags": [
          "API Key Management"
        ],
        "operationId": "get_api_keys",
        "summary": "Returns metadata for every active key on your account.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/api-keys/{keyId}": {
      "delete": {
        "tags": [
          "API Key Management"
        ],
        "operationId": "delete_api_keys_By_keyId",
        "summary": "Instantly disables a key. Future requests with it return 401 INVALID_API_KEY.",
        "parameters": [
          {
            "name": "keyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/usage": {
      "get": {
        "tags": [
          "API Key Management"
        ],
        "operationId": "get_usage",
        "summary": "Returns total calls, trial status, and current credit balance.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/bank-transactions": {
      "get": {
        "tags": [
          "Bank Transactions"
        ],
        "operationId": "get_bank_transactions",
        "summary": "Returns recent transactions across all connected bank accounts.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/bank-transactions/push": {
      "post": {
        "tags": [
          "Bank Transactions"
        ],
        "operationId": "post_bank_transactions_push",
        "summary": "Pushes a single transaction from your bank feed integration.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/bank-transactions/batch-import": {
      "post": {
        "tags": [
          "Bank Transactions"
        ],
        "operationId": "post_bank_transactions_batch_import",
        "summary": "Import many transactions at once (e.g. from a CSV parse or statement OCR).",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/bank-transactions/{id}/match": {
      "post": {
        "tags": [
          "Bank Transactions"
        ],
        "operationId": "post_bank_transactions_By_id_match",
        "summary": "Links a bank transaction to an invoice, receipt, expense, or bill.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/bank-transactions/{id}/unmatch": {
      "post": {
        "tags": [
          "Bank Transactions"
        ],
        "operationId": "post_bank_transactions_By_id_unmatch",
        "summary": "Removes a match. The original document reverts to unreconciled.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/bank-transactions/auto-match": {
      "post": {
        "tags": [
          "Bank Transactions"
        ],
        "operationId": "post_bank_transactions_auto_match",
        "summary": "Runs the matching algorithm across all unmatched transactions. Returns counts of matched and unmatched.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/bank-transactions/sync-balance": {
      "post": {
        "tags": [
          "Bank Transactions"
        ],
        "operationId": "post_bank_transactions_sync_balance",
        "summary": "Updates the stored balance on a bank account from the bank feed.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/bills": {
      "get": {
        "tags": [
          "Bills & Payments"
        ],
        "operationId": "get_bills",
        "summary": "Returns bills for a business, newest first.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Bills & Payments"
        ],
        "operationId": "post_bills",
        "summary": "Records a supplier bill in accounts payable.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/bills/{id}": {
      "get": {
        "tags": [
          "Bills & Payments"
        ],
        "operationId": "get_bills_By_id",
        "summary": "Fetches one bill. Supplier PII is decrypted in the response.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "put": {
        "tags": [
          "Bills & Payments"
        ],
        "operationId": "put_bills_By_id",
        "summary": "Edits an unpaid bill. Paid and voided bills are immutable.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/bills/{id}/void": {
      "post": {
        "tags": [
          "Bills & Payments"
        ],
        "operationId": "post_bills_By_id_void",
        "summary": "Cancels an unpaid bill and reverses its GL entry.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/bills/{id}/payments": {
      "post": {
        "tags": [
          "Bills & Payments"
        ],
        "operationId": "post_bills_By_id_payments",
        "summary": "Applies a payment. WHT is computed and transferred to the payable account automatically.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "get": {
        "tags": [
          "Bills & Payments"
        ],
        "operationId": "get_bills_By_id_payments",
        "summary": "Returns all payments applied to this bill.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/capital-contributions": {
      "get": {
        "tags": [
          "Capital Contributions"
        ],
        "operationId": "get_capital_contributions",
        "summary": "Returns every capital contribution, newest first.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Capital Contributions"
        ],
        "operationId": "post_capital_contributions",
        "summary": "Records an owner/investor contribution and posts the GL entry.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/capital-contributions/{id}": {
      "get": {
        "tags": [
          "Capital Contributions"
        ],
        "operationId": "get_capital_contributions_By_id",
        "summary": "GET /v1/capital-contributions/{id}",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/chart-of-accounts": {
      "get": {
        "tags": [
          "Chart of Accounts"
        ],
        "operationId": "get_chart_of_accounts",
        "summary": "Returns every account on the business's COA.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Chart of Accounts"
        ],
        "operationId": "post_chart_of_accounts",
        "summary": "Adds a new account to the COA. Cannot overlap with system account codes.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/chart-of-accounts/{id}": {
      "get": {
        "tags": [
          "Chart of Accounts"
        ],
        "operationId": "get_chart_of_accounts_By_id",
        "summary": "Fetches one account with current balance.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "put": {
        "tags": [
          "Chart of Accounts"
        ],
        "operationId": "put_chart_of_accounts_By_id",
        "summary": "Update name, subcategory, or description. System accounts allow name/category edits only.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/credit-notes": {
      "get": {
        "tags": [
          "Credit Notes"
        ],
        "operationId": "get_credit_notes",
        "summary": "Returns credit notes for a business, newest first.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Credit Notes"
        ],
        "operationId": "post_credit_notes",
        "summary": "Creates a draft (or directly posts with post=true).",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/credit-notes/{id}": {
      "get": {
        "tags": [
          "Credit Notes"
        ],
        "operationId": "get_credit_notes_By_id",
        "summary": "Returns the credit note plus its allocations.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "put": {
        "tags": [
          "Credit Notes"
        ],
        "operationId": "put_credit_notes_By_id",
        "summary": "Edits a draft. Posted credit notes are terminal and reject updates.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "delete": {
        "tags": [
          "Credit Notes"
        ],
        "operationId": "delete_credit_notes_By_id",
        "summary": "Deletes a draft. Posted credit notes cannot be deleted — they are terminal.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/credit-notes/{id}/post": {
      "post": {
        "tags": [
          "Credit Notes"
        ],
        "operationId": "post_credit_notes_By_id_post",
        "summary": "Flips status draft → posted; GL posting runs asynchronously.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/credit-notes/{id}/apply": {
      "post": {
        "tags": [
          "Credit Notes"
        ],
        "operationId": "post_credit_notes_By_id_apply",
        "summary": "Allocates the credit to specific invoices (or bills, supplier-side). Up to 50 per call, atomic.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/credit-notes/{id}/allocations/{allocId}/unapply": {
      "post": {
        "tags": [
          "Credit Notes"
        ],
        "operationId": "post_credit_notes_By_id_allocations_By_allocId_unapply",
        "summary": "Reverses a specific allocation, freeing the credit back onto the note.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "allocId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/customers": {
      "get": {
        "tags": [
          "Customers"
        ],
        "operationId": "get_customers",
        "summary": "Returns active customers, sorted by name.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Customers"
        ],
        "operationId": "post_customers",
        "summary": "Creates a customer with the full field set.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/customers/{id}": {
      "get": {
        "tags": [
          "Customers"
        ],
        "operationId": "get_customers_By_id",
        "summary": "Fetches one customer.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "put": {
        "tags": [
          "Customers"
        ],
        "operationId": "put_customers_By_id",
        "summary": "Updates any of name, email, phone, address, companyName, tin.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "delete": {
        "tags": [
          "Customers"
        ],
        "operationId": "delete_customers_By_id",
        "summary": "Marks the customer inactive. Historical invoices and receipts are preserved.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/customers/search": {
      "get": {
        "tags": [
          "Customers"
        ],
        "operationId": "get_customers_search",
        "summary": "Substring match on name or email, among active customers only.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/customers/find-or-create": {
      "post": {
        "tags": [
          "Customers"
        ],
        "operationId": "post_customers_find_or_create",
        "summary": "Idempotent lookup by email. Returns existing customer if found, otherwise creates one.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/debit-notes": {
      "get": {
        "tags": [
          "Debit Notes"
        ],
        "operationId": "get_debit_notes",
        "summary": "Returns debit notes for a business, newest first.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Debit Notes"
        ],
        "operationId": "post_debit_notes",
        "summary": "Creates a draft (or posts with post=true).",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/debit-notes/{id}": {
      "get": {
        "tags": [
          "Debit Notes"
        ],
        "operationId": "get_debit_notes_By_id",
        "summary": "Fetches one debit note.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "put": {
        "tags": [
          "Debit Notes"
        ],
        "operationId": "put_debit_notes_By_id",
        "summary": "Edits a draft. Posted debit notes reject edits — void them and reissue instead.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "delete": {
        "tags": [
          "Debit Notes"
        ],
        "operationId": "delete_debit_notes_By_id",
        "summary": "Deletes a draft. Posted DNs are voided instead.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/debit-notes/{id}/post": {
      "post": {
        "tags": [
          "Debit Notes"
        ],
        "operationId": "post_debit_notes_By_id_post",
        "summary": "Flips status draft → posted; GL posting runs asynchronously.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/debit-notes/{id}/void": {
      "post": {
        "tags": [
          "Debit Notes"
        ],
        "operationId": "post_debit_notes_By_id_void",
        "summary": "Cancels a posted debit note and creates a reversing journal entry.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/documents/invoice/{invoiceId}/pdf": {
      "post": {
        "tags": [
          "Document Generation"
        ],
        "operationId": "post_documents_invoice_By_invoiceId_pdf",
        "summary": "Generates an invoice PDF with your logo, business address, and line items.",
        "parameters": [
          {
            "name": "invoiceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/documents/receipt/{receiptId}/pdf": {
      "post": {
        "tags": [
          "Document Generation"
        ],
        "operationId": "post_documents_receipt_By_receiptId_pdf",
        "summary": "Receipt PDF with payment breakdown and invoice allocation.",
        "parameters": [
          {
            "name": "receiptId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/documents/quotation/{quotationId}/pdf": {
      "post": {
        "tags": [
          "Document Generation"
        ],
        "operationId": "post_documents_quotation_By_quotationId_pdf",
        "summary": "Quotation PDF with validity date and terms.",
        "parameters": [
          {
            "name": "quotationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/documents/financial-statement/pdf": {
      "post": {
        "tags": [
          "Document Generation"
        ],
        "operationId": "post_documents_financial_statement_pdf",
        "summary": "Combined P&L, Balance Sheet, and Cash Flow for a period.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/documents/vat-return/pdf": {
      "post": {
        "tags": [
          "VAT Return"
        ],
        "operationId": "post_documents_vat_return_pdf",
        "summary": "Generates a PDF VAT return for a filing period.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/documents/vat-return/excel": {
      "post": {
        "tags": [
          "VAT Return"
        ],
        "operationId": "post_documents_vat_return_excel",
        "summary": "Same data as the PDF, formatted as the FIRS e-filing Excel template.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/documents/wht-certificate/{certificateId}/pdf": {
      "post": {
        "tags": [
          "WHT Certificates"
        ],
        "operationId": "post_documents_wht_certificate_By_certificateId_pdf",
        "summary": "Generates the WHT certificate PDF. Valid for 1 hour.",
        "parameters": [
          {
            "name": "certificateId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/documents/payslip/{payslipId}/pdf": {
      "post": {
        "tags": [
          "Document Generation"
        ],
        "operationId": "post_documents_payslip_By_payslipId_pdf",
        "summary": "Employee payslip with earnings, deductions, and net pay.",
        "parameters": [
          {
            "name": "payslipId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/employees": {
      "get": {
        "tags": [
          "Employees"
        ],
        "operationId": "get_employees",
        "summary": "Returns employees, optionally filtered by status.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Employees"
        ],
        "operationId": "post_employees",
        "summary": "Adds an employee to the directory. Does not run payroll.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/employees/{id}": {
      "get": {
        "tags": [
          "Employees"
        ],
        "operationId": "get_employees_By_id",
        "summary": "GET /v1/employees/{id}",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "put": {
        "tags": [
          "Employees"
        ],
        "operationId": "put_employees_By_id",
        "summary": "Edits employee fields. Changes apply to the next payroll run.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/employees/{id}/deactivate": {
      "post": {
        "tags": [
          "Employees"
        ],
        "operationId": "post_employees_By_id_deactivate",
        "summary": "Marks an employee inactive. They're excluded from future payroll runs, but historical payslips remain.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/employees/{id}/activate": {
      "post": {
        "tags": [
          "Employees"
        ],
        "operationId": "post_employees_By_id_activate",
        "summary": "Re-activates an inactive employee.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/enterprise/businesses": {
      "get": {
        "tags": [
          "Enterprise Management"
        ],
        "operationId": "get_enterprise_businesses",
        "summary": "Returns the businesses linked to your enterprise, newest first.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      },
      "post": {
        "tags": [
          "Enterprise Management"
        ],
        "operationId": "post_enterprise_businesses",
        "summary": "Creates a Firebase Auth user (or finds one by email), creates the business document with COA seeded, and links it to your enterprise.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/enterprise/businesses/{businessId}": {
      "delete": {
        "tags": [
          "Enterprise Management"
        ],
        "operationId": "delete_enterprise_businesses_By_businessId",
        "summary": "Unlinks the business from the enterprise. Does NOT delete data — the owner retains access independently.",
        "parameters": [
          {
            "name": "businessId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/enterprise/usage": {
      "get": {
        "tags": [
          "Enterprise Management"
        ],
        "operationId": "get_enterprise_usage",
        "summary": "Aggregate API usage across all businesses in the enterprise for a date range.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/enterprise/wallet": {
      "get": {
        "tags": [
          "Enterprise Management"
        ],
        "operationId": "get_enterprise_wallet",
        "summary": "Returns the enterprise wallet balance, lifetime topups and spend, and next billing date.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/enterprise/wallet/topup": {
      "post": {
        "tags": [
          "Enterprise Management"
        ],
        "operationId": "post_enterprise_wallet_topup",
        "summary": "Records a wallet topup. Settlement happens out-of-band; the reference is for your reconciliation.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/expenses": {
      "get": {
        "tags": [
          "Expenses"
        ],
        "operationId": "get_expenses",
        "summary": "Returns the most recent expenses for a business.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Expenses"
        ],
        "operationId": "post_expenses",
        "summary": "Creates and immediately posts an expense (unless you pass status: draft).",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/expenses/{id}": {
      "get": {
        "tags": [
          "Expenses"
        ],
        "operationId": "get_expenses_By_id",
        "summary": "GET /v1/expenses/{id}",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "put": {
        "tags": [
          "Expenses"
        ],
        "operationId": "put_expenses_By_id",
        "summary": "Edits description, date, category, or tags. Amounts cannot be edited — void and recreate instead.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/expenses/{id}/void": {
      "post": {
        "tags": [
          "Expenses"
        ],
        "operationId": "post_expenses_By_id_void",
        "summary": "Posts a reversing journal entry and marks the expense voided.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/fixed-assets": {
      "get": {
        "tags": [
          "Fixed Assets"
        ],
        "operationId": "get_fixed_assets",
        "summary": "Returns every asset on the books, newest first.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Fixed Assets"
        ],
        "operationId": "post_fixed_assets",
        "summary": "Registers a new asset. The purchase JE is posted if `postAcquisitionJE: true`.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/fixed-assets/{id}": {
      "get": {
        "tags": [
          "Fixed Assets"
        ],
        "operationId": "get_fixed_assets_By_id",
        "summary": "Fetches one asset with its depreciation schedule.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/fixed-assets/depreciate": {
      "post": {
        "tags": [
          "Fixed Assets"
        ],
        "operationId": "post_fixed_assets_depreciate",
        "summary": "Runs depreciation for all active assets and posts the combined JE.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/fixed-assets/{id}/dispose": {
      "post": {
        "tags": [
          "Fixed Assets"
        ],
        "operationId": "post_fixed_assets_By_id_dispose",
        "summary": "Records disposal. Computes gain or loss vs carrying value and posts the JE.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/businesses/{businessId}/intelligence/health-score": {
      "get": {
        "tags": [
          "Business Intelligence"
        ],
        "operationId": "get_businesses_By_businessId_intelligence_health_score",
        "summary": "Returns the composite business score (0–1000) with weighted category breakdown and 6-month history.",
        "parameters": [
          {
            "name": "businessId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/businesses/{businessId}/intelligence/health-analysis": {
      "get": {
        "tags": [
          "Business Intelligence"
        ],
        "operationId": "get_businesses_By_businessId_intelligence_health_analysis",
        "summary": "Narrative health analysis with revenue and cash-flow history plus driver breakdowns.",
        "parameters": [
          {
            "name": "businessId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/businesses/{businessId}/intelligence/cross-sell-signals": {
      "get": {
        "tags": [
          "Business Intelligence"
        ],
        "operationId": "get_businesses_By_businessId_intelligence_cross_sell_signals",
        "summary": "AI-detected cross-sell opportunities derived from transaction patterns.",
        "parameters": [
          {
            "name": "businessId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/businesses/{businessId}/intelligence/churn-risk": {
      "get": {
        "tags": [
          "Business Intelligence"
        ],
        "operationId": "get_businesses_By_businessId_intelligence_churn_risk",
        "summary": "Attrition risk assessment blended from engagement and financial signals.",
        "parameters": [
          {
            "name": "businessId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/businesses/{businessId}/intelligence/cash-flow-forecast": {
      "get": {
        "tags": [
          "Business Intelligence"
        ],
        "operationId": "get_businesses_By_businessId_intelligence_cash_flow_forecast",
        "summary": "Projected cash position at 30/60/90-day horizons, with confidence bands.",
        "parameters": [
          {
            "name": "businessId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/invoices": {
      "get": {
        "tags": [
          "Invoices"
        ],
        "operationId": "get_invoices",
        "summary": "Returns the most recent invoices for a business, newest first.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Invoices"
        ],
        "operationId": "post_invoices",
        "summary": "Creates a draft invoice. GL posting happens automatically when you mark it sent.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/invoices/{id}": {
      "get": {
        "tags": [
          "Invoices"
        ],
        "operationId": "get_invoices_By_id",
        "summary": "Fetches one invoice by ID.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "put": {
        "tags": [
          "Invoices"
        ],
        "operationId": "put_invoices_By_id",
        "summary": "Edits a draft invoice. Finalised invoices are immutable — void and recreate instead.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/journal-entries": {
      "get": {
        "tags": [
          "Journal Entries"
        ],
        "operationId": "get_journal_entries",
        "summary": "Paginated list, newest first.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Journal Entries"
        ],
        "operationId": "post_journal_entries",
        "summary": "Creates a draft JE. It doesn't hit the ledger until posted.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/journal-entries/{id}": {
      "get": {
        "tags": [
          "Journal Entries"
        ],
        "operationId": "get_journal_entries_By_id",
        "summary": "GET /v1/journal-entries/{id}",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/journal-entries/{id}/post": {
      "post": {
        "tags": [
          "Journal Entries"
        ],
        "operationId": "post_journal_entries_By_id_post",
        "summary": "Moves a draft JE to posted. Updates COA balances atomically.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/journal-entries/{id}/reverse": {
      "post": {
        "tags": [
          "Journal Entries"
        ],
        "operationId": "post_journal_entries_By_id_reverse",
        "summary": "Creates a mirror JE (debits and credits swapped) and marks both as reversed.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/loans": {
      "get": {
        "tags": [
          "Loans"
        ],
        "operationId": "get_loans",
        "summary": "Returns all loans on the books.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Loans"
        ],
        "operationId": "post_loans",
        "summary": "Records a loan. Disbursement JE posts on status `active`.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/loans/{id}": {
      "get": {
        "tags": [
          "Loans"
        ],
        "operationId": "get_loans_By_id",
        "summary": "Fetches one loan with amortization summary.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/loans/{id}/repayments": {
      "post": {
        "tags": [
          "Loans"
        ],
        "operationId": "post_loans_By_id_repayments",
        "summary": "Records a loan repayment. Splits into principal and interest and posts the JE.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/officers/{officerId}/profile": {
      "get": {
        "tags": [
          "Account Officers"
        ],
        "operationId": "get_officers_By_officerId_profile",
        "summary": "Returns the officer's identity, branch/region, role, and headline stats.",
        "parameters": [
          {
            "name": "officerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/officers/{officerId}/portfolio": {
      "get": {
        "tags": [
          "Account Officers"
        ],
        "operationId": "get_officers_By_officerId_portfolio",
        "summary": "Full list of businesses assigned to the officer with RAG health indicators and key financial metrics.",
        "parameters": [
          {
            "name": "officerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/officers/{officerId}/portfolio-summary": {
      "get": {
        "tags": [
          "Account Officers"
        ],
        "operationId": "get_officers_By_officerId_portfolio_summary",
        "summary": "Aggregate stats across the officer's entire portfolio.",
        "parameters": [
          {
            "name": "officerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/officers/{officerId}/alerts": {
      "get": {
        "tags": [
          "Account Officers"
        ],
        "operationId": "get_officers_By_officerId_alerts",
        "summary": "Active alerts across the officer's portfolio (declining revenue, negative cash flow, covenant breaches, etc.) sorted by severity.",
        "parameters": [
          {
            "name": "officerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/officers/{officerId}/cross-sell-pipeline": {
      "get": {
        "tags": [
          "Account Officers"
        ],
        "operationId": "get_officers_By_officerId_cross_sell_pipeline",
        "summary": "Cross-sell opportunities across the officer's portfolio, grouped by product with funnel metrics.",
        "parameters": [
          {
            "name": "officerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/officers/{officerId}/scorecard": {
      "get": {
        "tags": [
          "Account Officers"
        ],
        "operationId": "get_officers_By_officerId_scorecard",
        "summary": "Performance metrics used for internal officer scoring — health distribution, loan conversions, response times, engagement.",
        "parameters": [
          {
            "name": "officerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/businesses/{businessId}/payments/generate-link": {
      "post": {
        "tags": [
          "Payments & Collections"
        ],
        "operationId": "post_businesses_By_businessId_payments_generate_link",
        "summary": "Generates a hosted payment link for an invoice. Share with the customer; Finora Business auto-reconciles on payment.",
        "parameters": [
          {
            "name": "businessId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/businesses/{businessId}/payments/tap-to-pay": {
      "post": {
        "tags": [
          "Payments & Collections"
        ],
        "operationId": "post_businesses_By_businessId_payments_tap_to_pay",
        "summary": "Creates an NFC payment session for in-person capture via the partner mobile app.",
        "parameters": [
          {
            "name": "businessId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/webhooks/alat-payment": {
      "post": {
        "tags": [
          "Payments & Collections"
        ],
        "operationId": "post_webhooks_alat_payment",
        "summary": "Webhook endpoint for the bank partner to notify Finora Business of payment completions. HMAC-SHA256 authenticated, not API-key.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/payroll/run": {
      "post": {
        "tags": [
          "Payroll & Payslips"
        ],
        "operationId": "post_payroll_run",
        "summary": "Computes and posts payroll for a month. Creates payslips for every active employee.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/payroll/runs": {
      "get": {
        "tags": [
          "Payroll & Payslips"
        ],
        "operationId": "get_payroll_runs",
        "summary": "Historical runs, newest first.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/payslips": {
      "get": {
        "tags": [
          "Payroll & Payslips"
        ],
        "operationId": "get_payslips",
        "summary": "Lists payslips. Filter by employee or period.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/payslips/{id}": {
      "get": {
        "tags": [
          "Payroll & Payslips"
        ],
        "operationId": "get_payslips_By_id",
        "summary": "Fetches one payslip with full earnings and deductions breakdown.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/petty-cash": {
      "get": {
        "tags": [
          "Petty Cash"
        ],
        "operationId": "get_petty_cash",
        "summary": "Paginated list, newest first.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Petty Cash"
        ],
        "operationId": "post_petty_cash",
        "summary": "Opens a petty cash request. Starts in `pending` status.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/petty-cash/{id}/approve": {
      "post": {
        "tags": [
          "Petty Cash"
        ],
        "operationId": "post_petty_cash_By_id_approve",
        "summary": "Manager approval. Does not move money — use disburse next.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/petty-cash/{id}/disburse": {
      "post": {
        "tags": [
          "Petty Cash"
        ],
        "operationId": "post_petty_cash_By_id_disburse",
        "summary": "Records the cash leaving the float. Posts DR Petty Cash Advance, CR Cash/Bank.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/petty-cash/{id}/retire": {
      "post": {
        "tags": [
          "Petty Cash"
        ],
        "operationId": "post_petty_cash_By_id_retire",
        "summary": "Submit receipts for an disbursed request. Posts DR Expense Account, CR Petty Cash Advance.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/products": {
      "get": {
        "tags": [
          "Products"
        ],
        "operationId": "get_products",
        "summary": "Returns active products, sorted by name.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Products"
        ],
        "operationId": "post_products",
        "summary": "Creates a product.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/products/{id}": {
      "get": {
        "tags": [
          "Products"
        ],
        "operationId": "get_products_By_id",
        "summary": "Fetches one product.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "put": {
        "tags": [
          "Products"
        ],
        "operationId": "put_products_By_id",
        "summary": "Updates any product field. Pass stockQuantity to adjust inventory.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/quotations": {
      "get": {
        "tags": [
          "Quotations"
        ],
        "operationId": "get_quotations",
        "summary": "Returns recent quotations, newest first.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Quotations"
        ],
        "operationId": "post_quotations",
        "summary": "Creates a draft quotation.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/quotations/{id}": {
      "get": {
        "tags": [
          "Quotations"
        ],
        "operationId": "get_quotations_By_id",
        "summary": "GET /v1/quotations/{id}",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "put": {
        "tags": [
          "Quotations"
        ],
        "operationId": "put_quotations_By_id",
        "summary": "Edits a draft or sent quotation. Accepted, declined, and converted quotations are immutable.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/quotations/{id}/send": {
      "post": {
        "tags": [
          "Quotations"
        ],
        "operationId": "post_quotations_By_id_send",
        "summary": "Marks a quotation as sent to the customer. Typically triggers an email (dashboard-configured).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/quotations/{id}/accept": {
      "post": {
        "tags": [
          "Quotations"
        ],
        "operationId": "post_quotations_By_id_accept",
        "summary": "Records customer acceptance. Does not create an invoice automatically — use convert-to-invoice.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/quotations/{id}/decline": {
      "post": {
        "tags": [
          "Quotations"
        ],
        "operationId": "post_quotations_By_id_decline",
        "summary": "Records a declined quotation.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/quotations/{id}/convert-to-invoice": {
      "post": {
        "tags": [
          "Quotations"
        ],
        "operationId": "post_quotations_By_id_convert_to_invoice",
        "summary": "Creates a draft invoice from the quotation. The quotation status advances to converted.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/receipts": {
      "get": {
        "tags": [
          "Receipts"
        ],
        "operationId": "get_receipts",
        "summary": "Most recent receipts for a business, newest first.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Receipts"
        ],
        "operationId": "post_receipts",
        "summary": "Records a payment. Pass allocations for an invoice payment, or omit for a cash sale.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/receipts/{id}": {
      "get": {
        "tags": [
          "Receipts"
        ],
        "operationId": "get_receipts_By_id",
        "summary": "Fetches one receipt by ID.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/reports/profit-loss": {
      "get": {
        "tags": [
          "Reports"
        ],
        "operationId": "get_reports_profit_loss",
        "summary": "Revenue, cost of sales, operating expenses, and net income for a date range.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/reports/balance-sheet": {
      "get": {
        "tags": [
          "Reports"
        ],
        "operationId": "get_reports_balance_sheet",
        "summary": "Assets, liabilities, and equity as of a point in time.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/reports/trial-balance": {
      "get": {
        "tags": [
          "Reports"
        ],
        "operationId": "get_reports_trial_balance",
        "summary": "Every ledger account with debit/credit balance. Must net to zero.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/reports/cash-flow": {
      "get": {
        "tags": [
          "Reports"
        ],
        "operationId": "get_reports_cash_flow",
        "summary": "Operating, investing, and financing activity for a date range.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/reports/dashboard": {
      "get": {
        "tags": [
          "Reports"
        ],
        "operationId": "get_reports_dashboard",
        "summary": "One-shot snapshot: cash position, AR/AP totals, MTD revenue, recent activity. Useful for building dashboards that show the same numbers as Finora Business's own.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/reports/ar-aging": {
      "get": {
        "tags": [
          "Reports"
        ],
        "operationId": "get_reports_ar_aging",
        "summary": "Outstanding receivables bucketed by age (current, 1–30, 31–60, 61–90, 90+).",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/reports/ap-aging": {
      "get": {
        "tags": [
          "Reports"
        ],
        "operationId": "get_reports_ap_aging",
        "summary": "Outstanding payables bucketed by age.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/reports/tax-compliance": {
      "get": {
        "tags": [
          "Reports"
        ],
        "operationId": "get_reports_tax_compliance",
        "summary": "Nigerian tax compliance status per tax type (VAT, WHT, CIT, PAYE). Paired with the tax module.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/reports/tax-summary": {
      "get": {
        "tags": [
          "Reports"
        ],
        "operationId": "get_reports_tax_summary",
        "summary": "Tax amounts due/paid for a date range.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/lending/products": {
      "get": {
        "tags": [
          "Smart Loans"
        ],
        "operationId": "get_lending_products",
        "summary": "Catalog of lending products offered through the integration.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/lending/eligibility": {
      "get": {
        "tags": [
          "Smart Loans"
        ],
        "operationId": "get_lending_eligibility",
        "summary": "Returns pre-qualified offers computed from live Finora Business financials — revenue consistency, cash runway, debt ratios, receivables quality.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/lending/apply": {
      "post": {
        "tags": [
          "Smart Loans"
        ],
        "operationId": "post_lending_apply",
        "summary": "Submits a loan application against a pre-qualified offer.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/lending/loans": {
      "get": {
        "tags": [
          "Smart Loans"
        ],
        "operationId": "get_lending_loans",
        "summary": "Returns active loans for the business with amortization schedules.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/lending/loans/{loanId}": {
      "get": {
        "tags": [
          "Smart Loans"
        ],
        "operationId": "get_lending_loans_By_loanId",
        "summary": "Full loan document with complete amortization schedule and installment history.",
        "parameters": [
          {
            "name": "loanId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/lending/loans/{loanId}/disbursement-sync": {
      "post": {
        "tags": [
          "Smart Loans"
        ],
        "operationId": "post_lending_loans_By_loanId_disbursement_sync",
        "summary": "Called by the bank partner when a loan is disbursed from core banking. Creates the Finora Business loan and posts the GL entry.",
        "parameters": [
          {
            "name": "loanId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/lending/loans/{loanId}/repayment-sync": {
      "post": {
        "tags": [
          "Smart Loans"
        ],
        "operationId": "post_lending_loans_By_loanId_repayment_sync",
        "summary": "Called by the bank partner when an auto-debit is collected. Updates the loan balance and posts the GL entry.",
        "parameters": [
          {
            "name": "loanId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/lending/loans/{loanId}/covenants": {
      "get": {
        "tags": [
          "Smart Loans"
        ],
        "operationId": "get_lending_loans_By_loanId_covenants",
        "summary": "Returns covenant compliance status computed from live Finora Business data.",
        "parameters": [
          {
            "name": "loanId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/lending/metrics": {
      "get": {
        "tags": [
          "Smart Loans"
        ],
        "operationId": "get_lending_metrics",
        "summary": "Returns the raw lending intelligence metrics used by the eligibility engine.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Enterprise-only endpoint. Retail API keys receive 403 ENTERPRISE_ONLY. Contact sales for enterprise access.",
        "x-enterprise-only": true
      }
    },
    "/suppliers": {
      "get": {
        "tags": [
          "Suppliers"
        ],
        "operationId": "get_suppliers",
        "summary": "Returns active suppliers for a business.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Suppliers"
        ],
        "operationId": "post_suppliers",
        "summary": "Creates a supplier record.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/suppliers/{id}": {
      "get": {
        "tags": [
          "Suppliers"
        ],
        "operationId": "get_suppliers_By_id",
        "summary": "Fetches one supplier.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "put": {
        "tags": [
          "Suppliers"
        ],
        "operationId": "put_suppliers_By_id",
        "summary": "Updates supplier fields. Allowed fields match the create body.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "delete": {
        "tags": [
          "Suppliers"
        ],
        "operationId": "delete_suppliers_By_id",
        "summary": "Marks the supplier inactive. Does not affect historical bills or expenses.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/suppliers/search": {
      "get": {
        "tags": [
          "Suppliers"
        ],
        "operationId": "get_suppliers_search",
        "summary": "Substring match on name, email, phone, or TIN.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/tax/compliance": {
      "get": {
        "tags": [
          "Tax & Compliance"
        ],
        "operationId": "get_tax_compliance",
        "summary": "Returns Nigerian tax compliance status per tax type, with filing deadlines and amounts due.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/tax/summary": {
      "get": {
        "tags": [
          "Tax & Compliance"
        ],
        "operationId": "get_tax_summary",
        "summary": "Total tax amounts charged and paid across VAT, WHT, and PAYE for a date range.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/webhooks": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "post_webhooks",
        "summary": "Creates a webhook. The response includes a signing secret — save it, it's shown once.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "get_webhooks",
        "summary": "Returns your registered webhooks (secrets are masked).",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/webhooks/{id}": {
      "put": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "put_webhooks_By_id",
        "summary": "Edit URL, events, or active status. The secret stays the same.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      },
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "delete_webhooks_By_id",
        "summary": "Permanently removes the webhook. In-flight events are abandoned (no retries).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/tax/wht-certificates": {
      "get": {
        "tags": [
          "WHT Certificates"
        ],
        "operationId": "get_tax_wht_certificates",
        "summary": "Returns all WHT certificates for the business.",
        "parameters": [
          {
            "name": "businessId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Business ID the call targets."
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Bearer API key. Generate one at app.finorabusiness.com/settings/api-integrations. Keys start with live_sk_ (production) or test_sk_ (free sandbox)."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "example": "VALIDATION_ERROR"
              },
              "message": {
                "type": "string"
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      },
      "SuccessEnvelope": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "object"
          },
          "meta": {
            "type": "object",
            "properties": {
              "requestId": {
                "type": "string"
              },
              "timestamp": {
                "type": "string",
                "format": "date-time"
              },
              "rateLimit": {
                "type": "object",
                "properties": {
                  "limit": {
                    "type": "integer"
                  },
                  "remaining": {
                    "type": "integer"
                  },
                  "reset": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              }
            }
          }
        }
      }
    },
    "responses": {
      "Success": {
        "description": "Successful response",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SuccessEnvelope"
            }
          }
        }
      },
      "BadRequest": {
        "description": "Validation or missing parameters",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Authenticated but not allowed (enterprise-only, suspended, billing)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded; respect retryAfter",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ]
}